Knowledge MCP

The server exposes seven camel_docs_* tools. The workflow manifest allowlists five of them for the generated Camel Kit workflow; the other two remain available to direct MCP clients.

General searches blend Lucene BM25 keyword scoring (20 percent) with a KNN vector search over 384-dimensional Granite embeddings (80 percent), then rerank the candidates with a local cross-encoder before applying the result limit. Keywords keep exact identifiers such as kafka, CVE-2024-22369 or autoOffsetReset from being displaced by semantically similar results; vectors find documents whose wording differs from the question. Component lookup uses exact field matching first and marks any full-text fallback as fuzzy.

If the embedding model is unavailable or does not match the index, the server disables vector retrieval and continues with BM25 and the reranker; if the reranker is unavailable, it returns the retrieval order. Embedding and reranking run locally through ONNX Runtime; queries are not sent to an external model API.

The index is published as knowledge-index.zip with an index.json manifest in a GitHub release of the knowledge repository; it is not inside the MCP Maven artifact, and normal use needs neither a clone of that repository nor the indexer. The server resolves the index lazily on the first knowledge query in each process. The published 0.0.2 runner uses its original manifest location in luigidemasi/camel-kit-knowledge; it remains available for existing installations.

Migrated source builds discover releases through https://api.github.com/repos/apache/camel-kit/releases, selecting the newest published knowledge-index-v1-YYYY.MM.DD-HHMMSS tag. Product tags, drafts, prereleases and other format channels are ignored. The v1 contract is Lucene 9, the model granite-embedding-small-english-r2-q8, 384 dimensions and manifest formatVersion: 1. Model/format mismatches are rejected before activation. Legacy manifests can omit format and dimension fields only when they identify the v1 model.

Downloaded archives are SHA-256 checked and activated atomically in ~/.camel-kit/knowledge-index/. Failed checks, downloads or activations keep the previous working cache. A pinned client falls back only to its exact cached version. Discovery follows at most ten pages of 100 releases each, with a five-second deadline per page; use an explicit manifest if the list exceeds this bound. The first monorepo index must be published before its discovery endpoint is usable; until then use a local index or explicit legacy manifest.

Rebuild with ./mvnw -B -pl knowledge/index -am -Prebuild-index install from the repository root. Maintainers review generated data before manually dispatching Index Release from main; the workflow validates retrieval with working vectors before publication. Index publication is independent of Kit and Knowledge server releases.

Rebuilding is a maintainer task. From a checkout of the knowledge repository:

The rebuild refreshes the Camel website’s release metadata and selects every supported LTS line, adding the latest release line only when it is not an LTS; it then resolves the latest release tags of those lines, renders their documentation, downloads the catalog metadata, parses release notes and advisories, enriches Jira and NVD data, generates or reuses cached embeddings and writes the Lucene files with the manifest skeleton. CVE enrichment needs no API key; requests are rate-limited and cached, and a failed lookup is retried at a later rebuild. The reviewed index is committed, and the manually dispatched release workflow packages and publishes the archive and the completed manifest after a retrieval-quality gate.

/camel-knowledge is a prescriptive question-and-answer layer over the five allowlisted tools. A standalone question runs in the primary session: component configuration goes to camel_docs_component_info, troubleshooting and best-practice questions go to camel_docs_search, and the answer cites its sources. When a pipeline stage needs documentation context, the generated instructions isolate the lookup in a read-only research role where the agent has one (Bob 2’s reviewer preset, Antigravity’s reviewer, Qwen’s reviewer leaf, OpenCode’s researcher task) and run it inline on Pi. The role returns a concise answer with references instead of raw search results, and a failed lookup is reported as missing evidence rather than replaced with invented documentation.