Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
107 lines (67 loc) · 4.31 KB

ARCHITECTURE.md

File metadata and controls

107 lines (67 loc) · 4.31 KB
Raw

Architecture

Muninn is an stdio MCP server for TypeScript codebase exploration. The runtime is intentionally simple: the server registers tools, tools call the indexer or query SQLite, and the parser extracts symbols and imports from TypeScript syntax trees.

Runtime Flow

MCP client
  -> stdio transport
  -> src/index.ts
  -> registered tool
  -> indexer/query layer
  -> per-repository SQLite database under .muninn-indexes/

The server entry point is src/index.ts. It creates an McpServer, registers tools from src/tools, connects a StdioServerTransport, and then waits for MCP requests.

Modules

src/index.ts

Owns MCP server construction and tool registration. A tool is only available to clients when its register function is imported and called here.

src/tools/explore_architecture.ts

Exposes explore_architecture. With reindex: true, it rebuilds the SQLite index for the requested repository. It then reads indexed files, symbols, and dependencies and returns a JSON architecture summary.

src/tools/index_repo.ts

Exposes index_repo. It rebuilds the SQLite index for the requested repository and returns a short text summary with the number of indexed files. Use this when callers only need to refresh the index before running lookup tools.

src/tools/search_symbol.ts

Exposes search_symbol. It opens the target repository database and searches the symbols table with a partial name match.

src/tools/get_symbol_links.ts

Exposes get_symbol_links. It looks up exact symbol definitions and dependency rows whose import text references the requested symbol name.

src/indexer/db.ts

Owns SQLite setup and indexing. openDB(repoPath) opens that repository's database under .muninn-indexes/ in the Muninn working directory and creates tables if needed. indexRepo(repoPath) clears old index rows for that repository database, finds TypeScript files, parses each one, and inserts the fresh result set in a transaction.

src/indexer/parser.ts

Owns Tree-sitter parsing. It parses each TypeScript file and walks the syntax tree to extract:

  • Function declarations.
  • Class declarations.
  • Import statements.

The exported TypeScript interfaces include additional symbol kinds for future parser coverage.

Index Files

The indexer scans **/*.ts from the target repository and ignores:

  • node_modules/**
  • dist/**
  • .muninn.db

The index is rebuilt by deleting existing rows from the symbols, dependencies, and files tables, then inserting a fresh set from the current file system state.

This rebuild-first approach keeps the index easy to reason about while the project is small. It trades performance for correctness and simplicity: every index run reflects the current scanned files, but large repositories will eventually need incremental updates and stale-file detection.

SQLite Schema

symbols

  • id: primary key.
  • name: symbol name.
  • kind: symbol kind.
  • file: absolute file path.
  • line: one-based source line.

dependencies

  • id: primary key.
  • from_file: absolute file path containing the import.
  • to_file: import source text.
  • imported_name: import statement text used for simple lookup.

files

  • id: primary key.
  • path: absolute indexed file path.
  • indexed_at: ISO timestamp for the indexing run.

Generated and Local Files

  • node_modules/ is installed dependency output.
  • dist/ is TypeScript build output.
  • .muninn-indexes/ contains local runtime databases for indexed repositories.
  • .muninn.db is the legacy local runtime database name.

These files are ignored by Git and should not be published as source.

Validation Flow

The repository uses bun run verify as the local and CI verification command. It runs TypeScript checking and builds the generated JavaScript output. Parser and indexing tests are planned but not implemented yet.

Current Limitations

  • The parser currently extracts function and class declarations, not every TypeScript declaration kind.
  • Import dependency targets are stored as import source text, not fully resolved absolute module paths.
  • Search and symbol-link results depend on the last indexing run; callers should reindex with index_repo or explore_architecture after source changes.
  • Tool responses are not paginated yet, so large repositories can produce large JSON responses.