Knowledge MCP

The Knowledge MCP server gives AI agents release-backed access to Apache Camel documentation, component references, migration guides, CVE advisories, release notes, and JIRA issues. The current index manifest reports 30,520 documents covering Camel 4.18 through 4.22. Index releases are rebuilt deliberately, so results reflect the installed index rather than a live crawl of the web.

7 MCP Tools

The server exposes seven camel_docs_* tools. Camel-Kit’s generated workflow uses a five-tool subset, described below.

camel_docs_component_info(component="kafka", version="4.18")

camel_docs_search(query="how to configure idempotent consumer", max_results=5)

camel_docs_cve_search(component="http", severity="HIGH")

camel_docs_release_info(version="4.18")

camel_docs_jira_lookup(jira_id="CAMEL-22784")

camel_docs_validate_endpoint(uri="kafka:orders?brokers=localhost:9092")

camel_docs_index_info()

Camel-Kit Workflow Allowlist

The server API has seven tools, while camel-kit-workflow.yaml intentionally lists these five tools for Camel-Kit’s documentation workflow:

Generated targets that support exact MCP filtering or approval lists receive this five-tool set. Other target schemas may expose the server namespace behind their own prompt policy. camel_docs_validate_endpoint and camel_docs_index_info remain available to direct MCP clients, but are not part of the generated Camel-Kit workflow allowlist.

Search Pipeline

General documentation search combines keyword precision with semantic retrieval:

The blended candidates are reranked by a local MiniLM cross-encoder before the requested result limit is applied. Component lookup uses exact component-field matching first and marks any full-text fallback as fuzzy. If the embedding model is unavailable or does not match the index stamp and stored-vector self-check, the server disables vector retrieval and continues with BM25 plus the reranker. If the reranker is unavailable, it returns the remaining retrieval order: hybrid when vectors are active, otherwise BM25.

What’s Indexed

The checked-in manifest reports 30,520 Lucene documents across Camel 4.18, 4.19, 4.20, 4.21, and 4.22.

Local Models

Embedding and reranking run locally through ONNX Runtime. Queries are not sent to an external model API.

Index Distribution and Cache

The Lucene 9.12.1 index is published as knowledge-index.zip plus an index.json manifest in a GitHub Release. It is not embedded in the normal MCP Maven artifact. Normal Camel-Kit setup does not require cloning the knowledge repository or running the indexer.

camel-kit init (or camel kit init) generates the target’s MCP configuration with the pinned Knowledge MCP JBang coordinate. The server resolves and opens the index lazily, on the first knowledge query that uses it, in this order:

1. knowledge.index.path — open an explicit local index directory directly.
2. knowledge.index.url — fetch the manifest, compare its version with the local cache, download knowledge-index.zip when needed, verify its SHA-256, extract it into a version directory, and replace the active-version marker.
3. A legacy classpath index, when one is present in an older bundled artifact.

The first query can therefore take longer while the index downloads and the local search models initialize. A successful MCP initialize handshake or tools/list response does not prove the index is ready. Call camel_docs_index_info to trigger initialization and check the installed index. If the manifest is unreachable and no index is available, the knowledge query reports an index-opening failure even though the handshake and tool listing succeeded.

The default manifest is https://github.com/luigidemasi/camel-kit-knowledge/releases/latest/download/index.json, and downloaded versions are opened directly from ~/.camel-kit/knowledge-index/. If a manifest check, download, checksum check, or activation fails, the server falls back to the readable active cached version when one exists. Malformed or unsupported archive URLs follow the same fallback. A first offline query needs either a populated cache or knowledge.index.path pointing to a local index.

The cache filesystem must support advisory file locks and atomic moves for both version directories and metadata. Activation writes a temporary marker beside current, then replaces current with an atomic filesystem move. If atomic marker replacement is unsupported or fails, the previous marker remains intact and the server continues with that cached version. Without a usable cache, the query fails. A later attempt can activate the download once the failure clears; retrying alone cannot add missing advisory-lock or atomic-move support. The extracted version directory also requires an atomic move, so a failed installation cannot leave a partially moved directory for a later attempt to reuse. Atomic moves do not guarantee durability across power loss. The current and previous index versions are retained after a successful update.

The manifest ETag is saved only after its version is active and is reused only for that version and manifest URL. Failed downloads, checksum checks, or marker replacements leave the previous validator unchanged, so a later attempt can retry the same release. Validator saving is best effort: a save failure does not undo activation, and pruning follows the save attempt. An HTTP 200 response without an ETag removes the old validator. Legacy ETags without a version and URL binding are ignored and refreshed through an unconditional manifest check.

Updates to a shared cache are serialized across threads and processes, including the manifest check, activation, and pruning. Cache sharing requires all clients to use this locking protocol; older clients without it must use a separate cache. When another updater holds the lock, a caller uses a readable active cache immediately. Without a usable cache, it waits at most five seconds in total for lock acquisition before the download attempt fails. If lock acquisition is unsupported or fails, a readable active cache remains usable; without one, the attempt fails.

HTTP connections have a three-second timeout. Manifest requests must finish within five seconds and archive requests within five minutes, including the response body. A timeout falls back to the readable active cache when available.

Downloads use separate staging directories; the next locked attempt removes recognized staging files left by an interrupted process, including legacy <version>.part entries only when they are real directories and the version prefix follows the safe-name rules below. New metadata files honor the process umask, and replacements preserve existing POSIX permissions.

For custom manifests, version must contain 1–128 ASCII letters, digits, dots, underscores or hyphens and begin with a letter or digit. Trailing dots, .part suffixes, current, etag, and Windows device names are reserved (case-insensitive). Version paths cannot escape the cache or point through symbolic links.

Rebuilding from Source

Index rebuilding is a contributor and release-maintainer task. From a checkout of camel-kit-knowledge, run:

./mvnw -pl index -Prebuild-index -am -B install

The rebuild resolves active Camel versions, fetches immutable release tags, renders documentation, downloads Camel Catalog metadata, parses release notes and CVE advisories, enriches available JIRA and NVD data, generates or reuses cached embeddings, and writes the Lucene files plus the manifest skeleton under index/src/main/resources/.

Rebuild on a branch, commit the generated index with a signed commit, and have it reviewed and merged before release. The manually dispatched Index Release workflow runs from main: it builds the reviewed, committed index without -Prebuild-index, runs the retrieval-quality gate with working vectors required, verifies that the index files remain unchanged, then packages and publishes the ZIP and completed manifest. Local source builds are not the normal end-user installation path.

Knowledge repository modules:

Camel Knowledge Skill

The Camel Knowledge skill (shown as /camel-knowledge or the target’s equivalent invocation) is a prescriptive Q&A layer over the five workflow-allowlisted tools. Standalone questions run in the primary session. When a pipeline needs documentation context, the generated instructions either isolate the lookup in a read-only research agent or run it inline when that target has no suitable subagent surface.

The research role returns a concise answer and source references instead of copying raw search results into the orchestrator context. A failed lookup is reported as missing evidence; it must not be replaced with fabricated documentation.

Next Steps

• MCP Integration — Camel MCP Server (catalog verification)
• Architecture Overview — Four-layer architecture
• Commands Reference — Full Camel Knowledge usage