Knowledge Base MCP API

This reference documents the current Knowledge Base MCP surface. The conceptual guide lives in Knowledge Base; this page keeps the tool catalog, sync routes, and config boundaries precise.

Source Of Truth

The MCP tool contract is generated from ai/mcp/server/knowledge-base/openapi.yaml. The OpenAPI document defines operation ids, request schemas, response schemas, read/admin tiers, and tool handbook metadata.

The server name is neo-knowledge-base. Its Chroma collection is neo-knowledge-base.

Read Tools

Use ask_knowledge_base for synthesized "how/why" questions. Use query_documents when you need raw source paths and will inspect the files yourself. Use get_class_hierarchy when inheritance determines the real implementation surface.

Extended Introspection

The deployment tools expose read-only bridge data. They do not expose Docker, shell, restart, or daemon control routes.

Deployment snapshots include a bounded tenantRepoSync section for pull-mode cloud ingestion. Use it when a KB is healthy but empty and tenant repositories are expected: it reports the orchestrator enablement gate, scheduler cadence, task state, effective repo-config counts/tiers, redacted per-repo due state, and stable failure reason codes without exposing clone URLs, credentials, or raw logs.

inspect_deployment and get_deployment_state_snapshot include a bridgeDiagnostics envelope when the orchestrator's deployment-state bridge can explain its own observation layer. That envelope reports non-secret runtime-access config such as the runtime mechanism, whether runtime access is enabled, the configured Compose project, allowlisted service keys, read operations, the bridge's effective service keys, and whether bounded logs are included. Per-service lookup failures also carry stable reason values and the Compose label filter used for the lookup, for example compose-service-no-match with com.docker.compose.service=<service>. This is diagnosis only: callers still receive no Docker socket, shell, restart, or arbitrary container enumeration.

Admin Tools

manage_knowledge_base(action: "sync") runs the local create + embed path. It has a synchronous volume gate: when the post-delta diff is larger than mcpSyncMaxChunks, use npm run ai:sync-kb for bulk re-embedding.

ingest_source_files is the cloud-facing push route. It validates tenant and repo context, accepts parsed chunks or raw source, applies server-owned tenant stamps, records deletion signals, and writes progress diagnostics.

Storage Boundary

Knowledge Base and Memory Core share one Chroma daemon and one unified persist directory from AiConfig.engines.chroma. The local default persist path is the unified Chroma directory under .neo-ai-data/chroma/unified; cloud deployments mount the same shape in the container volume.

Separation happens by collection:

The Knowledge Base collection uses a dummy embedding function because vectors are supplied explicitly by Neo's embedding service before Chroma upsert.

Embedding Providers

The Knowledge Base uses TextEmbeddingService with the resolved embeddingProvider setting. That setting is the same provider selector used by Memory Core.

Do not document the Knowledge Base as tied to one remote provider. Local providers serve embeddings from their own host; GEMINI_API_KEY is not a general KB requirement.

Embedding Budget Guardrails

Local embedding providers have an input-size guardrail before provider invocation:

• VectorService estimates each final embedding input, splits recoverable oversized chunks, and skips chunks that remain over the safe processing band.
• IngestionService repeats the precheck for tenant ingestion so callers get a durable diagnostic even when the offending source cannot be written as a graph row.
• Oversized skips record bounded metadata such as tenant, repo, source path, provider, model, input size, and safe limit. Raw source content is not emitted.

This turns embedding overflow into inspectable substrate friction instead of an unbounded provider failure.

Common Operations

Ask A Grounded Question

{
  "query": "How does ViewModel binding propagate updates?",
  "type": "src",
  "limit": 5
}

Call ask_knowledge_base when you want a concise answer with citations.

Retrieve Raw References

{
  "query": "grid keyboard navigation",
  "type": "all",
  "limit": 10
}

Call query_documents when the next step is reading the returned files directly.

Sync Local Changes

For small deltas:

{
  "action": "sync"
}

For large deltas, use the bulk script named by the volume gate:

npm run ai:sync-kb

Related Guides

• Knowledge Base
• Knowledge Base Enhancement Strategy
• Tenant Ingestion Model
• Deployment Configuration