# agentmap

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/raymondchins/agentmap  
**GitHub Stars:** 50  
**npm Downloads (last month):** 464  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agentmap

## Description
TS/JS-accurate repo map for coding agents: a ts-morph import/symbol graph, 8 MCP query tools.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agentmap": {
    "command": "npx",
    "args": ["-y","@raymondchins/agentmap"]
  }
}
```

## Documentation

## What agentmap does

The agentmap MCP server gives coding agents a queryable map of a TypeScript or JavaScript repository. Its graph connects files and symbols through resolved imports and definitions, allowing an agent to ask targeted repository-navigation questions instead of reading broad file lists or dumping the project into context. Vue single-file components are also supported.

The package is aimed at tasks such as locating an existing helper, finding the file that defines a symbol, identifying files affected by a change, and producing a ranked repository digest under a token budget.

## How it works

agentmap uses ts-morph, which relies on the TypeScript compiler rather than text matching. The graph can account for tsconfig path mappings, Vite and webpack aliases, `#imports` subpaths, and monorepo workspaces. It also follows re-export chains to identify the file that actually declares a symbol.

The CLI provides five query modes: `--find` for symbols or existing functionality, `--relates` for a file's dependents and change impact, `--map` for a ranked repository digest, `--any` for automatic query routing, and the default map command for repository status. A personalized PageRank ranking is applied across file and symbol graphs. The command-line examples report an approximately 1.2-second cold build and approximately 0.1-second cached query, though timings depend on the repository and environment.

The agentmap MCP server operates locally. A cache is stored at `.claude/agentmap/map.json`; cached results are used for a clean tree at the same `HEAD`, while uncommitted supported-language edits trigger a rebuild.

## Setup and configuration

Run the scoped npm package with Node.js 20 or newer:

```bash
npx @raymondchins/agentmap --relates path/to/file.ts
```

The scoped package name matters because the unscoped `agentmap` name refers to another package. From a repository checkout, commands can also be run with `node agentmap.mjs`.

For automatic maintenance and agent guidance, run:

```bash
npx @raymondchins/agentmap --install-hooks
npx @raymondchins/agentmap --install-skill
```

The hooks rebuild the map after commits, while the skill installation is documented for Claude Code, Cursor, Codex, Gemini, OpenCode, and Copilot.

## Tools and capabilities

The agentmap MCP server and CLI support these grounded capabilities:

- Search for a symbol or existing helper with `--find`.
- Trace files that depend on a selected file with `--relates`.
- Generate a ranked repository map with `--map` and an optional `--tokens N` budget.
- Route an arbitrary request with `--any`.
- Report repository graph information, including file counts, feature counts, and a top hub.
- Detect unresolved-import health through an `edgeCoverage` signal and warnings.

## Limitations and notes

Coverage is limited to TypeScript, JavaScript, and Vue SFC repositories. A small, single-file lookup may cost more than direct `cat` and `grep`, so the tool is not automatically cheaper for every query. Its published token figures are estimates based on character counts divided by four, and describe context-token volume rather than answer quality or elapsed time.

`--relates` returns the complete dependent set, which can be longer than a simple filename list. That trades shorter output for dependency precision. Results also depend on imports resolving correctly; the tool reports map health rather than silently treating an incomplete graph as reliable.

_Full upstream README: https://allmcps.com/mcp/agentmap/readme_