MCP Integrations & Connectors
Relevant source files
The following files were used as context for generating this wiki page:
MCP (Model Context Protocol) Integrations and Connectors provide a governed framework for Isabella Villaseñor AI to interact with external data repositories and internal vector indices. This system enables the Model Context Protocol to fetch evidence, verify claims, and maintain cognitive sovereignty by strictly regulating how external tools and data sources are accessed and utilized.
The architecture ensures that every connector adheres to zero-trust policies, including mandatory manifest validation, data classification checks, and cryptographic audit trails. It explicitly separates data retrieval from epistemic verification, ensuring that retrieved information is treated as "insufficient" until further internal validation occurs.
Sources: src/lib/mcp/index.ts:2-9, src/lib/mcp-adapters/zenodo-mcp-adapter.ts:3-15
Core Architecture & Governance
The MCP framework operates through a centralized registry that manages ConnectorManifest objects. These manifests define the security posture and capabilities of each connector. The system enforces a multi-layered validation pipeline before allowing any external calls.
Integration Pipeline
- Manifest Validation: Checks the connector's identity and required scopes.
- OAuth Policy: Validates credentials and applies rotation or revocation.
- Data Classification: Ensures the manifest allows the specific class of data being requested.
- Resilience: Applies rate limits, timeouts, and circuit breakers (Closed, Open, Half-Open).
- Execution: Performs the actual retrieval via specific adapters (e.g., Zenodo, LITLE).
- Audit: Records the transaction in an immutable audit log.
This diagram illustrates the cascading validation steps required for a successful MCP connector execution.
MCP Adapters
Adapters translate Isabella's internal queries into repository-specific requests. The project currently supports two primary adapters: ZenodoMCPAdapterV2 for public research and LitleMCPAdapterV2 for local vector indices.
Zenodo/OSF V2 Adapter
This adapter interfaces with the Zenodo API to retrieve scholarly records. It employs lexical scoring (BM25-like) for relevance but explicitly marks all results with an insufficient epistemic status because retrieval does not equal verification.
- Validation: Uses Zod (
ZenodoHitSchema) to reject malformed repository data. - Provenance: Generates digests for responses and queries to ensure integrity.
- Lexical Scoring: Calculates similarity based on token intersection divided by the geometric mean of token counts.
Sources: src/lib/mcp-adapters/zenodo-mcp-adapter.ts:19-58, tests/mcp-adapters.test.ts:31-50
LITLE Local Vector Adapter
The Library of Independent Trust & Verification (LITLE) adapter performs dense retrieval against a local JSON vector index. It requires normalized embeddings and validates model compatibility via modelDigest.
- Integrity: Rejects indices if the
modelDigestdoes not match the query embedding. - Mathematical Strictness: Validates that vectors are finite and normalized before performing cosine similarity.
- Local Governance: Results include
evidenceIdprefixed withlitle:and source URLs using thebookpi://protocol.
Sources: src/lib/mcp-adapters/litle-mcp-adapter.ts:15-115, tests/mcp-adapters.test.ts:98-102
Data Structures and Contracts
The system uses strictly typed interfaces to ensure consistency across different adapters and the central hub.
| Component | Description | Source |
|---|---|---|
MCPQueryContext | Defines request parameters like assertion, maxResults, and deadlineMs. | tests/mcp-adapters.test.ts:8-16 |
MCPQueryResultV2 | Standardized response containing relevance, epistemic status, and provenance. | src/lib/mcp-adapters/zenodo-mcp-adapter.ts:105-135 |
ConnectorManifest | Static declaration of connector identity, scopes, and network modes. | src/lib/mcp/index.ts:18-23 |
LitleIndex | Schema for local vector stores, including dimension and embeddingModel. | src/lib/mcp-adapters/litle-mcp-adapter.ts:28-34 |
Implementation in Hub & Server
The server initializes these adapters during startup and exposes their status via a dedicated health endpoint.
Server Initialization
The server.ts file triggers initializeDefaultAdapters() to mount the Zenodo and LITLE connectors into the runtime hub.
Sources: server.ts:1174-1175
Hub View Interface
The IsabellaHubView component provides a "Tools Catalog" where developers can inspect registered MCP tools and test them within a sandbox.
- Execution: Sends requests to
POST /api/v1/isabella/tools/execute. - Monitoring: Displays the total count of registered tools and their risk ratings.
Sources: src/components/Hub/IsabellaHubView.tsx:84-88, src/components/Hub/IsabellaHubView.tsx:690-725
This sequence shows the flow of a tool execution request from the user interface through the governance layers.
Security & Provenance Requirements
Every MCP interaction must produce a responseDigest using SHA3-256 to ensure that the data retrieved has not been tampered with during transit. The framework prohibits any connector from modifying Isabella's core policies, models, or cryptographic keys.
Sources: src/lib/mcp-adapters/zenodo-mcp-adapter.ts:6-12, src/lib/mcp-adapters/litle-mcp-adapter.ts:10-14
The MCP Integrations & Connectors system establishes a high-trust boundary for external data, ensuring that Isabella Villaseñor AI remains epistemologically sovereign while leveraging global scientific knowledge and local memory stores.