AgentRamen

What the agentRamen MCP server does

The agentRamen MCP server builds a searchable representation of a repository’s source files and Git history. It stores the index in .agentramen/graph.db by default, keeping the database and optional embeddings within the checkout in local mode. Retrieval combines file paths, symbols, imports, Git history, co-change information, and, when enabled, local semantic similarity.

The resulting context is intended for coding tasks where selecting relevant files matters. It can return ranked files and source excerpts, inspect dependencies and dependents, identify hotspots and co-changes, review file history, and expose repository structure. The project also supports graph export and cached commit snapshot queries according to the repository description.

How it works

The indexer reads the working tree and Git history, applies language analysis, and writes the resulting graph to SQLite. agentramen init creates configuration, indexes the repository, and can offer a GitHub Actions caller workflow. agentramen index and agentramen update provide full or incremental refresh operations, while status reports index state.

Queries can be made through local MCP stdio, the command-line interface, or a local HTTP interface. Context retrieval accepts a task description and a budget, while impact, explanation, history, and search operations target specific files or queries. The configured budget covers selected files and related evidence such as paths, digests, commits, and team memories where applicable.

The default installation uses Python’s standard library and conservative analysis. Tree-sitter parsing, local embeddings, and model-based token counting are optional packages. Semantic inference runs locally after any required model weights are downloaded.

Setup and configuration

Install the package with Python 3.10 or newer, change to the repository to analyze, and run agentramen init. The generated .agentramen.yml controls incremental indexing, Git history retention, co-change edges, semantic retrieval, context budgets, token counting, and ignore rules. .agentramenignore adds patterns to the built-in and YAML ignore rules.

Optional extras are available for Tree-sitter parsing, semantic retrieval, tokenizer support, and the central service. The tokenizer option can use tiktoken; otherwise, context sizing falls back to approximate character-based counting. The database is ignored by Git.

Tools and capabilities

The agentRamen MCP server supports repository context retrieval, impact analysis, file explanation, file history lookup, text search, indexing, updates, and status queries through the documented command and MCP interfaces. Context requests can specify a budget, and results identify whether token counts used tiktoken or the approximate method.

Local mode keeps indexed excerpts and embeddings in the checkout. An optional central mode can publish sanitized, commit-pinned snapshots to a centrally hosted, OIDC-protected read-only MCP service. The central option is intended for teams that operate the receiving infrastructure.

Limitations and notes

Language analysis for non-Python files is conservative unless the Tree-sitter extra and a suitable grammar are available; otherwise, the project falls back to regex analysis. Semantic retrieval is disabled by default and requires the semantic extra. Enabling central snapshots transfers indexed source that passes credential heuristics, so teams should review their data-handling requirements before using it.

The project is described as a working alpha. Configuration uses a dependency-free YAML subset, and unsupported or malformed values produce setting-specific errors. The local HTTP, MCP, and CLI interfaces operate against the repository’s generated index rather than a hosted code search service.