Javadoc MCP Server
haarer/javadoc-mcp-server
Indexa e busca documentação Javadoc com BM25 + embeddings vetoriais
Ver no GitHubServidor MCP que indexa JARs Javadoc em SQLite com busca híbrida BM25 + vetores. Permite upload, indexação e consulta de documentação Java com suporte a busca por palavra-chave e linguagem natural, integrando backends de embedding como llama.cpp, OpenAI ou vLLM.
Instalação
npx convez-ai haarer/javadoc-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar documentação de classes e métodos Java pelo IDE ou agente IA
- Busca semântica em múltiplas bibliotecas Java simultaneamente
- Integração com Claude MCP para assistência técnica em projetos Java
Veredito

Ferramenta bem arquitetada para integrar documentação Java em workflows MCP, com suporte flexível a múltiplos backends de embedding. Ideal para equipes que querem assistência IA contextual sobre código Java legado ou grandes bases de bibliotecas.
README
A tradução para o português deste README ainda está na fila.
Javadoc MCP Server
MCP server that indexes Javadoc JARs into SQLite with hybrid BM25 + vector search.
Quick start
cd /workspace/javadoc-mcp-server
uv sync
uv run javadoc-mcp
Server starts on 0.0.0.0:8600 (override with env vars below).
Connect your MCP client to http://host.containers.internal:8600.
Embedding backend
The server uses an OpenAI-compatible /v1/embeddings API endpoint. No local model loading required — it calls the embedding service over HTTP.
Supported backends:
- llama.cpp — self-hosted, CPU/GPU inference (see below)
- OpenAI —
https://api.openai.com/v1/embeddings - vLLM, Ollama, LiteLLM, etc.
Running llama.cpp server
/build/bin/llama-server \
--hf-repo sabafallah/bge-large-en-v1.5-Q4_K_M-GGUF \
--hf-file bge-large-en-v1.5-q4_k_m.gguf \
--port 8000 \
--embedding \
-c 8192
The MCP server defaults to bge-large-en-v1.5 (1024 dim) on localhost:8000, so you can start it directly:
uv run javadoc-mcp
Or override settings explicitly:
JAVADOC_EMBED_API_URL=http://localhost:8000/v1/embeddings \
JAVADOC_EMBED_MODEL=bge-large-en-v1.5 \
JAVADOC_EMBED_DIM=1024 \
uv run javadoc-mcp
Using OpenAI API
JAVADOC_EMBED_API_URL=https://api.openai.com/v1/embeddings \
JAVADOC_EMBED_API_KEY=sk-... \
JAVADOC_EMBED_MODEL=text-embedding-3-small \
JAVADOC_EMBED_DIM=1536 \
uv run javadoc-mcp
Environment variables
| Variable | Default | Description |
|---|---|---|
JAVADOC_MCP_HOST | 0.0.0.0 | Bind address |
JAVADOC_MCP_PORT | 8600 | Port |
JAVADOC_INDEX_DIR | ./data | Index storage directory |
JAVADOC_INDEX_PATH | data/javadoc.db | SQLite DB path |
JAVADOC_JARS_DIR | data/jars | Directory for uploaded JAR files |
JAVADOC_EMBED_API_URL | http://localhost:8000/v1/embeddings | Embedding API endpoint |
JAVADOC_EMBED_API_KEY | (none) | Bearer token for API auth |
JAVADOC_EMBED_MODEL | bge-large-en-v1.5 | Model name sent to API |
JAVADOC_EMBED_DIM | 1024 | Embedding vector dimension |
JAVADOC_EMBED_BATCH | 256 | Embedding batch size |
MCP tools
| Tool | Description |
|---|---|
lookup_symbol(fqn) | Look up documentation by fully qualified name (e.g. com.example.MyClass or com.example.MyClass#methodName). Returns name, kind, signature, summary, description. If not found, suggests similar FQNs. |
search_docs(query, limit, jar_filter) | Search indexed Javadoc by keyword or natural language query. |
list_packages(jar_filter) | List all packages. Optionally filter by jar name. |
list_classes(package, jar_filter) | List classes, interfaces, and enums in a package. |
add_jar(name) | Upload a Javadoc JAR via the /upload-jar HTTP endpoint (see below). Returns status: "indexing"; indexing runs in background. |
remove_jar(name) | Remove a previously indexed JAR and all its symbols. Cannot remove JARs currently indexing. |
list_jars() | List all indexed JARs with name, hash, symbol count, status, and error message. |
jar_status(name) | Check indexing status of a JAR. Returns status (indexing, indexed, failed), symbols_indexed, and error_message. |
Uploading a JAR
curl -F jar=@/path/to/javadoc.jar -F name=my-jar http://host:8600/upload-jar
JAR files are stored by SHA-256 hash of their content to prevent duplicate uploads.
Hybrid search
- BM25 via SQLite FTS5 on
fqn,name,package,summary,description - Vector cosine similarity via dot product
- Reciprocal rank fusion:
score = 1/(k+bm25_rank) + 1/(k+vec_rank), k=60 - Returns top-N merged results
Indexing
Each indexed symbol stores: FQN, kind, name, package, signature, summary, full description, HTML path, source JAR, and an embedding blob (dimension matches JAVADOC_EMBED_DIM).
Indexing uses a two-worker async pipeline:
- Parser worker: reads HTML files from the JAR, parses with BeautifulSoup, pushes batches to a queue
- Embedder worker: pulls batches from the queue, calls the embedding API, inserts into SQLite
Symbols include all members (methods, fields, constructors), not just classes. FQN format: package.ClassName#memberName for members.
Background indexing
add_jar returns immediately with status: "indexing". Use jar_status(name) to check progress:
indexing— in progress,symbols_indexedshows count so farindexed— complete,symbols_indexedshows total countfailed— error occurred,error_messagecontains details
While a JAR is indexing, search and lookup tools still work. You cannot remove a JAR while it's indexing.
Embedding failure handling
If the embedding API is unreachable or returns an error, the indexer falls back to zero-byte embeddings. The symbols are still stored in the DB with FTS5 search working; embeddings can be regenerated by re-indexing.
Architecture
mcp_server/
server.py # MCP app, 8 tool handlers, HTTP upload endpoint, uvicorn
indexer.py # Async producer-consumer pipeline: parser + embedder workers
embedder.py # HTTP client for OpenAPI embedding (fail-fast, short timeouts)
database.py # SQLite schema, FTS5, vector queries, indexing status tracking
parser.py # BeautifulSoup Javadoc HTML -> structured data (all members)
config.py # Settings (port, index path, API URL, model, RRF k, batch size)
Dependencies
mcp[streamable-http]— MCP framework + HTTP transportbeautifulsoup4— Javadoc HTML parsingrequests— HTTP client for embedding API callssqlite3— stdlib (FTS5 virtual table)