convez.ai
MCP ServerIntegração & APIsIntermediário
haarer

Javadoc MCP Server

haarer/javadoc-mcp-server

Indexa e busca documentação Javadoc com BM25 + embeddings vetoriais

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-server

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

VariableDefaultDescription
JAVADOC_MCP_HOST0.0.0.0Bind address
JAVADOC_MCP_PORT8600Port
JAVADOC_INDEX_DIR./dataIndex storage directory
JAVADOC_INDEX_PATHdata/javadoc.dbSQLite DB path
JAVADOC_JARS_DIRdata/jarsDirectory for uploaded JAR files
JAVADOC_EMBED_API_URLhttp://localhost:8000/v1/embeddingsEmbedding API endpoint
JAVADOC_EMBED_API_KEY(none)Bearer token for API auth
JAVADOC_EMBED_MODELbge-large-en-v1.5Model name sent to API
JAVADOC_EMBED_DIM1024Embedding vector dimension
JAVADOC_EMBED_BATCH256Embedding batch size

MCP tools

ToolDescription
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

  1. BM25 via SQLite FTS5 on fqn, name, package, summary, description
  2. Vector cosine similarity via dot product
  3. Reciprocal rank fusion: score = 1/(k+bm25_rank) + 1/(k+vec_rank), k=60
  4. 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_indexed shows count so far
  • indexed — complete, symbols_indexed shows total count
  • failed — error occurred, error_message contains 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 transport
  • beautifulsoup4 — Javadoc HTML parsing
  • requests — HTTP client for embedding API calls
  • sqlite3 — stdlib (FTS5 virtual table)
Ver o original no GitHub

Bom para

Relacionados