Automated software archaeology: excavate user stories, dependency maps, and structure from legacy code with LangGraph + MCP agents
Archaeocode exposes 22 tools across graph DB, knowledge base, RAG, and static analysis domains. Most tools have descriptions (18/22), but quality is inconsistent: many descriptions are placeholder text acknowledging mock implementations rather than production-ready guidance. Parameter schemas are present but sparse, most tools lack per-parameter descriptions, violating the rubric baseline (100% of A+ tools have param descriptions). No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. Error handling is minimal; most tools return JSON blobs without recovery guidance. Naming is generally clear (verb_noun pattern), but composition issues exist: kb_query and kb_retrieve overlap significantly, and kb_context duplicates retrieval logic. Output schemas are undocumented, LLMs cannot predict response structure. This is a typical community server: functional but not production-ready.
Calculate cyclomatic complexity of source code.
Calculate graph metrics including node count, edge count, density, and average degree.
Split a code document into chunks for embedding. Args: content: Source code content to chunk language: Programming language (python, java, javascript, etc.) chunk_size: Maximum chunk size in characters (default: 1000) chunk_overlap: Overlap between chunks in characters (default: 200) Returns: List of chunks with metadata
Create nodes in the dependency graph. This is a placeholder. In production, it would: - Connect to Neo4j database - Execute CREATE Cypher queries - Handle transactions and error recovery
Create relationships between nodes in the dependency graph. This is a placeholder. In production, it would: - Connect to Neo4j database - Match source and target nodes - Create relationships with properties
Detect circular dependencies in the graph.
Missing per-parameter descriptions on 18+ tools. Parameters like 'mode', 'depth', 'language' lack guidance on valid values, ranges, or semantics. LLMs cannot infer whether 'mode' accepts 'local|global|hybrid' or free-form strings.
No output schemas documented. Tools return JSON but LLMs cannot predict field names, types, or structure. E.g., does kb_query return {answer, mode, sources} or {result, metadata}? Forces LLMs to guess and parse unstructured responses.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 48 | 2026-07-28+ | v2 |
Generate embeddings for code chunks. This tool currently returns mock embeddings. In production, it would: - Call OpenAI Embeddings API (text-embedding-3-large) - Use Cohere embeddings - Use HuggingFace embedding models Args: chunks: List of text chunks to embed Returns: Chunks with embeddings added
Extract code entities (classes, functions, methods, imports) from source code.
Find all dependencies of a node. This traverses outgoing relationships to find what a node depends on.
Find all nodes that depend on a given node. This traverses incoming relationships to find what depends on a node.
Index an entire codebase into a vector store. This is a placeholder. In production, it would: - Connect to Qdrant/Weaviate/Chroma/Pinecone - Chunk each file - Generate embeddings - Store in vector database Args: files: List of file objects with 'content', 'path', 'language' keys collection_name: Vector store collection name (default: code_embeddings) Returns: Indexing statistics
Add documents (design docs, tickets, runbooks, interview notes) to the knowledge base. Args: documents: List of {"path": str, "content": str} objects extract: Run LLM entity/relation extraction (needs an LLM); default from config
Return the prompt-ready context block the knowledge base would give an LLM. Useful for agents that want to reason over the evidence themselves.
Export the knowledge graph as an Obsidian-compatible Markdown wiki. Args: output_dir: Directory to write index.md and entities/*.md into max_nodes: Cap on exported entities
Get the neighbourhood of an entity in the knowledge graph. Args: label: Entity name (file path, "path::Function", "Story: ...") or "*" for everything max_depth: Traversal depth from the entity max_nodes: Cap on returned nodes
Ask the knowledge base a question and get an LLM-synthesized answer. Args: question: Natural-language question about the analyzed system mode: Retrieval mode — local (entity-centric), global (relation/theme-centric), hybrid, naive (chunks only) or mix (graph + chunks; default) response_type: Free-text answer format hint, e.g. "Bullet Points", "Single Paragraph" working_dir: Knowledge base directory (default: KB_WORKING_DIR or data/knowledge_base) workspace: Logical partition inside shared back-ends (default: KB_WORKSPACE) Returns: The answer text plus the retrieval mode used
Structured retrieval without answer synthesis (no LLM required). Args: question: Search query (natural language, identifier, file name, ...) mode: local / global / hybrid / naive / mix (default from config) top_k: Maximum entities/relations to retrieve chunk_top_k: Maximum text chunks to retrieve working_dir: Knowledge base directory workspace: Logical partition inside shared back-ends Returns: Matching entities, relationships, text chunks and references
Size, entity-type breakdown and configuration of the knowledge base.
Parse source code into an Abstract Syntax Tree (AST) using tree-sitter.
Execute a Cypher query against the graph database. This is a placeholder. In production, it would: - Execute the Cypher query - Return results as list of records
Perform semantic search over indexed code. This is a placeholder. In production, it would: - Embed the query using the same embedding model - Search vector store for similar embeddings - Return top K results with similarity scores Args: query: Search query (natural language or code) top_k: Number of results to return (default: 5) filter_language: Optional language filter (python, java, etc.) collection_name: Vector store collection to search (default: code_embeddings) Returns: List of relevant code chunks with similarity scores
Find shortest path between two nodes in the dependency graph.
Placeholder descriptions on 8 tools (create_nodes, create_relationships, query_graph, embed_code, index_codebase, kb_stats, detect_cycles, calculate_metrics) state 'This is a placeholder' or 'In production, it would...' instead of documenting actual behavior. Agents cannot trust these descriptions.
Overlapping tool semantics: kb_query, kb_retrieve, and kb_context all perform retrieval with different output formats. LLMs cannot distinguish when to use each. Consolidate into kb_query (with response_type param) and kb_retrieve (structured only), or rename for clarity.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. create_nodes, create_relationships, kb_add_documents, kb_export_wiki, index_codebase are WRITE operations but lack destructiveHint. Agents cannot reason about side effects or retry safety.