Content
# Tool List
> Compiling any code repository into a layered knowledge graph, enabling AI programming tools to truly understand the project through the MCP protocol - rather than making changes based on intuition.
[](https://pypi.org/project/craftsman-map/)
[](LICENSE)
[](https://www.python.org/)
[](https://afdian.com/a/EthanXue)
**Five-layer architecture, corresponding to five tasks:**
- **INGEST**: Multi-language parsing + document asset import → unified graph
- **MAP**: Functional block clustering + progressive disclosure → token efficiency
- **NAVIGATE**: Impact analysis + git history → dual evidence
- **UNDERSTAND**: Translating code into human language → wiki description + LLM enhancement
- **TRACE**: Entry to exit call chain tracking → core capability for large models to locate bugs
---
## Installation
```bash
pip install craftsman-map
```
Dependency description:
- **Zero forced dependencies**: Python parsing uses built-in `ast`, graph uses pure Python, out-of-the-box
- **Optional enhancements**: `pip install tree-sitter tree-sitter-javascript tree-sitter-typescript tree-sitter-go` → unlock multi-language support for JS/TS/Go
- **Git history**: `pip install dulwich` → no need to install git binaries, pure Python reads git history
---
## Quick Start
```bash
# 1. Create an index in your project root directory (must run before making changes)
cd /path/to/your-project
craftsman-map index
# 2. View functional block map (progressive disclosure of the first layer)
craftsman-map map
# 3. Search for symbols
craftsman-map search "UserService"
# 4. View symbol details + neighbors
craftsman-map symbol "src/auth/service.py::UserService"
# 5. Analyze impact (what changes will affect)
craftsman-map impact "src/auth/service.py::UserService.login"
# 6. Drill down (progressive disclosure of the second layer)
craftsman-map explore "src/auth/service.py::UserService" --depth 2
# 7. Hotspot analysis (which files change most frequently)
craftsman-map hotspots
# 8. Statistical overview
craftsman-map overview
# 9. Layered architecture view (automatically marks entry/core/tool layers)
craftsman-map layers
# 10. Automatically identify real entry points
craftsman-map entrypoints
# 11. Work chain: track call path from entry to exit
craftsman-map trace "src/main.py::main"
# 12. Generate wiki description (rule-based, zero-cost)
craftsman-map wiki
# 13. Get description material package for a functional block (for LLM to generate descriptions)
craftsman-map describe --cluster 0
# 14. Write LLM-generated description back to cache
craftsman-map desc --cluster 0 --text "This module is responsible for..."
```
---
## Command List
| Command | Effect | Typical Use Case |
|------|------|---------|
| `index [PATH]` | Establish/refresh index | First use or after code changes |
| `overview` | Node/edge/language statistics | Understand project scale |
| `map` | Functional block overview | Progressive disclosure of the first layer |
| `search QUERY` | Symbol search | Find functions/classes/variables |
| `symbol ID` | Symbol details + neighbors | Precisely view a symbol |
| `impact ID` | Impact analysis | Assess affected range before changes |
| `explore ID` | Progressive drilling | Expand neighbors from a node |
| `hotspots` | Change hotspots + co-variation relationships | Find high-risk areas |
| `layers` | Layered architecture view | Automatically mark entry/core/tool/configuration layers |
| `entrypoints` | Identify real entry points | Find the actual call start of the project |
| `trace ID` | Work chain tracking | Complete call path from entry to exit |
| `wiki` | Generate wiki description | Translate code into human language (rule-based, zero-cost) |
| `describe` | Output description material package | Generate high-quality descriptions for LLM |
| `desc` | Write back LLM description | Cache generated descriptions into the graph |
All commands default to **JSON** output (suitable for large model parsing), add `--pretty` for formatted output.
---
## Why use it for Large Models?
**The real pain point of LLM is not "not understanding code", but "not finding the right place + seeing too much".**
`craftsman-map` design principles:
1. **Progressive disclosure saves tokens**: `map` provides functional block summaries (10 lines), and then `explore` drills down - without swallowing 5000 functions at once.
2. **Confidence system**: Each edge has a `confidence` field (static evidence 1.0 / ambiguity 0.6 / suspension 0.4), letting large models know which are certain facts and which are inferences.
3. **`next_actions` guidance**: Each output includes "next possible commands", eliminating large model guesses.
4. **Dual impact**: Static call graph + git co-variation history. Pure static graphs may miss implicit coupling that is not directly called but often changed together.
---
## MCP Access (enabling large models to call autonomously)
`craftsman-map` has a built-in MCP server, standard stdio JSON-RPC protocol:
```bash
craftsman-map serve-mcp
```
Configure in **AWS Code / Cursor / Cline / Windsurf / Continue**:
```json
{
"mcpServers": {
"craftsman-map": {
"command": "craftsman-map",
"args": ["serve-mcp"]
}
}
}
```
The `clients/` directory has configuration files for each platform, copy and paste to use. MCP provides 16 tools, covering all CLI commands, and AI can call them autonomously as needed.
---
## Supported Languages
| Language | Support Status | Backend |
|------|---------|------|
| Python | ✅ Built-in, zero dependency | Built-in `ast` |
| JavaScript | ✅ Optional | tree-sitter |
| TypeScript | ✅ Optional | tree-sitter |
| Go | ✅ Optional | tree-sitter |
| Markdown / txt | ✅ Built-in | Text parsing |
| Images / binary assets | ✅ Built-in (records path, does not read content) | AssetParser |
---
## Project Structure
```bash
craftsman-map/
├── craftsman_map/
│ ├── cli.py # CLI entry
│ ├── mcp_server.py # MCP stdio server (16 tools)
│ ├── indexer.py # INGEST layer: scan + parse + build graph
│ ├── git_history.py # git history dimension (dulwich pure Python)
│ ├── graph/
│ │ ├── model.py # Node / Edge data model (with confidence)
│ │ ├── store.py # CodeGraph storage + clustering + serialization
│ │ └── linker.py # Reference resolution
│ ├── parsers/
│ │ ├── base.py # Parser abstract interface
│ │ ├── python_parser.py
│ │ ├── ts_parser.py # JS/TS/Go (tree-sitter)
│ │ └── doc_parser.py # Markdown / assets
│ ├── understand/
│ │ ├── wiki.py # Understanding layer: rule-based description + material package + injection
│ │ ├── view.py # Layered view
│ │ └── trace.py # Work chain tracking
│ └── commands/
│ ├── core.py
│ └── understand.py
├── tests/ # 68 tests, all passed
├── clients/ # MCP configuration files for each platform
└── pyproject.toml
```
---
## Development & Testing
```bash
pip install -e ".[dev]"
pytest tests/ -v
```
**68 passed, 0 skipped, 0 failed.**
---
## 💝 Sponsor
If `craftsman-map` helps you, consider sponsoring to support ongoing development.
[](https://afdian.com/a/EthanXue)
---
## Design Philosophy
The core belief of `craftsman-map`: **LLM understands code repositories not by "seeing everything" but by "seeing the right part".**
Compiling code repositories into structured knowledge graphs, through deterministic CLI precise disclosure - five-layer architecture corresponds to five tasks: ingestion, layering, navigation, understanding, and querying. Each layer can be used independently or combined into a complete code understanding pipeline.
Feel free to raise issues and PRs.
---
## Contact
Feel free to reach out by email for any questions, suggestions, or collaboration.
- 📧 Email: [545118959@qq.com](mailto:545118959@qq.com)
- 💬 Issues: [github.com/EthanXue666/craftsman-map/issues](https://github.com/EthanXue666/craftsman-map/issues)
---
## License
MIT — free to use for personal and commercial projects.
