Muninn

Muninn is a Model Context Protocol (MCP) server that indexes TypeScript repositories and exposes code-navigation tools over stdio. It stores local SQLite indexes under the Muninn project directory and lets MCP clients search symbols, inspect symbol links, and summarize file-level dependencies.

Features

• Indexes TypeScript source files with Tree-sitter.
• Stores symbols, imports, and indexed file metadata in per-repository databases under .muninn-indexes/.
• Exposes MCP tools for architecture exploration and symbol lookup.
• Rebuilds the index on demand so results reflect the current repository state.

Project Status

Muninn is an early-stage local MCP server. The current implementation is useful for exploring TypeScript repositories, but it intentionally keeps the first version small: it extracts function and class declarations, records import statements, and rebuilds indexes on demand. Broader declaration coverage, resolved import graphs, stale-index detection, pagination, and automated tests are tracked as follow-up work.

Requirements

• Bun for dependency installation and script execution.
• Node.js compatible with the generated ESM output.
• A TypeScript repository to index.

Installation

bun install

Muninn currently runs from a local clone. Generated dependencies and build output are intentionally ignored by Git; recreate them locally with bun install and bun run build.

Development

Run the TypeScript source directly:

bun run dev

Build the JavaScript output:

bun run build

Run the built server:

bun run start

bun run build writes generated JavaScript, declarations, and source maps to dist/. That directory is ignored because it can be recreated from src.

Run the local verification command before opening a change:

bun run verify

MCP Usage

Muninn runs as an stdio MCP server. Build the server before using it from an LLM client:

bun run build

For Claude Desktop or another MCP client, add Muninn to the client's MCP server configuration:

{
  "mcpServers": {
    "muninn": {
      "command": "node",
      "args": [
        "/home/esprazj/Documents/Projects/muninn/dist/index.js"
      ]
    }
  }
}

The built config is the recommended setup for normal use. During local development, you can point the client at the dev script, which rebuilds Muninn and then starts the compiled server with Node:

{
  "mcpServers": {
    "muninn": {
      "command": "bun",
      "args": ["run", "dev"],
      "cwd": "/home/esprazj/Documents/Projects/muninn"
    }
  }
}

Typical Workflow

1. Start Muninn from an MCP client.
2. Call index_repo for the repository you want to inspect, or call explore_architecture with reindex: true when you want indexing and a summary in one request.
3. Use search_symbol to find definitions by partial symbol name.
4. Use get_symbol_links to inspect definitions and imports for a specific symbol.

The first indexing run creates a database for that repository under .muninn-indexes/ in the Muninn working directory. Re-run indexing after source changes when you need fresh results.

Design Tradeoffs

• Indexes live under Muninn's working directory instead of the target repository, so exploring a project does not write into that project.
• Reindexing currently clears and rebuilds a repository database. This is simple and predictable, but incremental indexing will scale better for large repositories.
• Import dependencies are stored from import declarations, not resolved through TypeScript module resolution yet.
• Lookup tools read the last index. Run index_repo again when source files change.

Tools

These are the tools registered by the server entry point in src/index.ts.

index_repo

Indexes a TypeScript repository and stores the result in a per-repository database under .muninn-indexes/.

Inputs:

• repo_path: absolute path to the repository root.

Output:

• Text summary with the number of indexed files and the database path.

Example input:

{
  "repo_path": "/absolute/path/to/project"
}

explore_architecture

Summarizes a TypeScript repository and can optionally rebuild the index first.

Inputs:

• repo_path: absolute path to the repository root.
• reindex: optional boolean. Set to true to rebuild that repository's database before reading results.

Output:

• Number of indexed files.
• List of discovered symbols.
• File dependency graph based on import declarations.

Example input:

{
  "repo_path": "/absolute/path/to/project",
  "reindex": true
}

search_symbol

Searches the indexed symbols table by partial name.

Inputs:

• repo_path: absolute path to the indexed repository root.
• query: partial symbol name to search for.

Output:

• Matching symbol names, kinds, files, and line numbers.

get_symbol_links

Finds symbol definitions and import references in the index.

Inputs:

• repo_path: absolute path to the indexed repository root.
• symbol_name: exact symbol name to inspect.

Output:

• Matching definitions from the symbols table.
• Import records whose text references the symbol name.

How Indexing Works

index_repo and explore_architecture with reindex: true call the same indexer for the target repository. The indexer:

1. Opens or creates a per-repository database under .muninn-indexes/ in the Muninn working directory.
2. Clears existing index rows.
3. Finds **/*.ts files while ignoring node_modules and dist.
4. Parses each file with Tree-sitter TypeScript.
5. Stores declarations and import statements in SQLite.

The database is local runtime state and is intentionally ignored by Git.

Data Model

Muninn stores three tables in each repository database:

• symbols: discovered declarations with name, kind, file, and line.
• dependencies: import statements with source file, imported path, and import text.
• files: indexed file paths and the timestamp for the indexing run.

The current parser records function and class declarations, plus import statements. Interfaces and variables are represented in the TypeScript types but are not fully extracted yet.

Project Structure

src/
  index.ts                  MCP server entry point
  indexer/
    db.ts                   SQLite schema and repository indexing
    parser.ts               Tree-sitter parsing for symbols and imports
  tools/
    explore_architecture.ts MCP architecture/indexing tool
    get_symbol_links.ts     MCP symbol reference tool
    index_repo.ts           MCP indexing tool
    search_symbol.ts        MCP symbol search tool

See docs/ARCHITECTURE.md for a deeper description of module responsibilities and runtime flow.

Public Repository Hygiene

The repository ignores local dependencies, generated build output, logs, editor settings, secrets, and SQLite runtime files. Keep bun.lock, source files, and documentation tracked. Do not commit:

• .muninn.db, .muninn-indexes/, or other generated databases.
• node_modules.
• dist build output unless the release process explicitly requires it.
• .env files or credentials.

If these files were committed before .gitignore existed, remove them from the Git index while keeping local copies:

git rm --cached -r node_modules dist .muninn.db .muninn-indexes

Validation

Pull requests and pushes to main run the GitHub Actions verification workflow. Run the same checks locally before opening a pull request:

bun install
bun run check
bun run test
bun run build

Or run the combined verification command:

bun run verify

bun run verify runs type checking, tests, and the build in the same order used for local validation. CI installs dependencies with bun install --frozen-lockfile and caches Bun's package cache from bun.lock.

Troubleshooting

bun run start cannot find dist/index.js

Run bun run build first. dist is generated output and is not tracked.

Search returns no symbols

Index the target repository first:

{
  "repo_path": "/absolute/path/to/project"
}

Results look stale

Run index_repo again, or run explore_architecture with reindex: true. The SQLite index is rebuilt from the current TypeScript files.

License

MIT License. See LICENSE.