m5-engine 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- m5_engine-1.0.0/PKG-INFO +157 -0
- m5_engine-1.0.0/README.md +125 -0
- m5_engine-1.0.0/m5_engine.egg-info/PKG-INFO +157 -0
- m5_engine-1.0.0/m5_engine.egg-info/SOURCES.txt +52 -0
- m5_engine-1.0.0/m5_engine.egg-info/dependency_links.txt +1 -0
- m5_engine-1.0.0/m5_engine.egg-info/entry_points.txt +2 -0
- m5_engine-1.0.0/m5_engine.egg-info/requires.txt +9 -0
- m5_engine-1.0.0/m5_engine.egg-info/top_level.txt +1 -0
- m5_engine-1.0.0/pyproject.toml +56 -0
- m5_engine-1.0.0/setup.cfg +4 -0
- m5_engine-1.0.0/src/__init__.py +0 -0
- m5_engine-1.0.0/src/api/webhooks.py +124 -0
- m5_engine-1.0.0/src/audit/__init__.py +3 -0
- m5_engine-1.0.0/src/audit/telemetry.py +338 -0
- m5_engine-1.0.0/src/auth.py +218 -0
- m5_engine-1.0.0/src/cli/__init__.py +1 -0
- m5_engine-1.0.0/src/cli/installer.py +11 -0
- m5_engine-1.0.0/src/cli/main.py +377 -0
- m5_engine-1.0.0/src/cli/setup_guide.py +268 -0
- m5_engine-1.0.0/src/cli/sync.py +80 -0
- m5_engine-1.0.0/src/cli/visual_server.py +625 -0
- m5_engine-1.0.0/src/config.py +25 -0
- m5_engine-1.0.0/src/context/__init__.py +1 -0
- m5_engine-1.0.0/src/context/context_engine.py +391 -0
- m5_engine-1.0.0/src/indexer/file_watcher.py +108 -0
- m5_engine-1.0.0/src/indexer/git_manager.py +106 -0
- m5_engine-1.0.0/src/indexer/progressive_indexer.py +298 -0
- m5_engine-1.0.0/src/logger.py +67 -0
- m5_engine-1.0.0/src/main.py +74 -0
- m5_engine-1.0.0/src/mcp_server.py +556 -0
- m5_engine-1.0.0/src/parser/ast_parser.py +301 -0
- m5_engine-1.0.0/src/parser/customizations.py +129 -0
- m5_engine-1.0.0/src/server.py +444 -0
- m5_engine-1.0.0/src/storage/local_db.py +337 -0
- m5_engine-1.0.0/src/tools/__init__.py +12 -0
- m5_engine-1.0.0/src/tools/dependency_graph.py +376 -0
- m5_engine-1.0.0/src/tools/hybrid_search.py +360 -0
- m5_engine-1.0.0/src/tools/line_reader.py +74 -0
- m5_engine-1.0.0/src/tools/multi_repo_graph.py +78 -0
- m5_engine-1.0.0/src/tools/test_impact.py +87 -0
- m5_engine-1.0.0/src/tools/vector_search.py +298 -0
- m5_engine-1.0.0/test/test_ast_parser.py +15 -0
- m5_engine-1.0.0/test/test_customizations.py +38 -0
- m5_engine-1.0.0/test/test_dependency_graph.py +30 -0
- m5_engine-1.0.0/test/test_git_manager.py +43 -0
- m5_engine-1.0.0/test/test_hybrid_search.py +99 -0
- m5_engine-1.0.0/test/test_mcp_http.py +111 -0
- m5_engine-1.0.0/test/test_mcp_server.py +111 -0
- m5_engine-1.0.0/test/test_multitenancy.py +96 -0
- m5_engine-1.0.0/test/test_progressive_indexer.py +104 -0
- m5_engine-1.0.0/test/test_telemetry.py +91 -0
- m5_engine-1.0.0/test/test_tenant_isolation.py +260 -0
- m5_engine-1.0.0/test/test_vector_search.py +28 -0
- m5_engine-1.0.0/test/test_webhook_delta.py +91 -0
m5_engine-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: m5-engine
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Intelligent, zero-overhead AST code context and dependency graph engine for AI coding agents,saving LLM token costs.
|
|
5
|
+
Author-email: Aman <lazyserp@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/m5-context-engine/m5
|
|
8
|
+
Project-URL: Documentation, https://github.com/m5-context-engine/m5#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/m5-context-engine/m5.git
|
|
10
|
+
Project-URL: Issues, https://github.com/m5-context-engine/m5/issues
|
|
11
|
+
Keywords: mcp,model-context-protocol,ast,code-graph,developer-tools,ai-agents,cursor,claude-code,copilot
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Requires-Python: >=3.9
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
Requires-Dist: tree-sitter>=0.20.0
|
|
25
|
+
Requires-Dist: pydantic>=2.0.0
|
|
26
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
27
|
+
Provides-Extra: enterprise
|
|
28
|
+
Requires-Dist: fastapi>=0.100.0; extra == "enterprise"
|
|
29
|
+
Requires-Dist: uvicorn>=0.22.0; extra == "enterprise"
|
|
30
|
+
Requires-Dist: qdrant-client>=1.6.0; extra == "enterprise"
|
|
31
|
+
Requires-Dist: fastembed>=0.2.0; extra == "enterprise"
|
|
32
|
+
|
|
33
|
+
# M5 — AST Code Knowledge Graph for AI Coding Agents
|
|
34
|
+
|
|
35
|
+
When AI agents work on your codebase, they spend most of their time (and your tokens) doing clumsy discovery: grepping files one by one, wandering through directory listings, and trying to reconstruct call hierarchies in their head.
|
|
36
|
+
|
|
37
|
+
**M5 fixes that.** It parses your codebase with Tree-sitter into an embedded, zero-overhead SQLite knowledge graph (`.m5/local_graph.db`). When your agent asks a question, M5 returns the exact code, upstream callers, downstream dependencies, and blast radius in **one single call**.
|
|
38
|
+
|
|
39
|
+
- **100% Local**: No Docker, no heavy background daemons, no cloud dependency.
|
|
40
|
+
- **Sub-50ms Incremental Sync**: Watches your files and updates only what changed when you save.
|
|
41
|
+
- **Zero-Friction MCP Integration**: Works with Claude Code, Cursor, VS Code / Copilot, Gemini CLI, Antigravity, and Codex.
|
|
42
|
+
- **Interactive Browser UI**: Visualize your architecture and dependency chains at `http://127.0.0.1:5555`.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 🚀 Quickstart
|
|
47
|
+
|
|
48
|
+
### 1. Install M5
|
|
49
|
+
Install globally using `pip` or `pipx`:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install m5-context
|
|
53
|
+
# or with pipx:
|
|
54
|
+
pipx install m5-context
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### 2. Connect Your AI Agent
|
|
58
|
+
Run the interactive setup wizard to get clean, copy-pasteable MCP config snippets for your editor:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
m5 setup
|
|
62
|
+
```
|
|
63
|
+
*(Or specify your tool directly: `m5 setup claude`, `m5 setup cursor`, `m5 setup vscode`)*
|
|
64
|
+
|
|
65
|
+
Paste the provided JSON block into your editor's MCP configuration. We don't silently rewrite your system files behind your back — you stay in full control.
|
|
66
|
+
|
|
67
|
+
### 3. Build Your Project Index
|
|
68
|
+
Navigate to any project repository and build the graph:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
cd your-project
|
|
72
|
+
m5 build
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
This scans your workspace and indexes all AST symbols and call edges into `.m5/local_graph.db` in under a second.
|
|
76
|
+
|
|
77
|
+
### 4. Keep It Fresh While You Code
|
|
78
|
+
Start the background watcher:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
m5 live
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Whenever you or your AI agent edits a file, M5 catches the change and updates the graph in $<50\text{ms}$.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 🔍 CLI Commands
|
|
89
|
+
|
|
90
|
+
| Command | What it does | Example |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `m5 setup` | Interactive manual setup wizard with exact MCP configs for your IDE | `m5 setup` or `m5 setup cursor` |
|
|
93
|
+
| `m5 build` | Scans workspace and builds AST knowledge graph into `.m5/` | `m5 build` |
|
|
94
|
+
| `m5 live` | Starts real-time file watcher (<50ms incremental sync on save) | `m5 live` |
|
|
95
|
+
| `m5 stats` | Shows index summary (files, AST symbols, call edges, DB size) | `m5 stats` |
|
|
96
|
+
| `m5 trace` | 1-shot surgical context: verbatim code + call flow + blast radius | `m5 trace "auth middleware token validation"` |
|
|
97
|
+
| `m5 peek` | View symbol definition & callers, or view line-numbered file | `m5 peek UserService` or `m5 peek src/auth.py` |
|
|
98
|
+
| `m5 find` | Search AST symbols by name, type, or pattern (FTS5 + B-tree) | `m5 find parse_jwt` |
|
|
99
|
+
| `m5 callers` | Find all functions and files calling a symbol | `m5 callers handle_request` |
|
|
100
|
+
| `m5 callees` | Find all functions called by a symbol | `m5 callees handle_request` |
|
|
101
|
+
| `m5 blast` | Multi-hop blast radius & affected files analysis before refactoring | `m5 blast DatabasePool --depth 2` |
|
|
102
|
+
| `m5 diff-tests` | Find test suites affected by modified files | `git diff --name-only \| m5 diff-tests --stdin` |
|
|
103
|
+
| `m5 view` | Open local browser visualizer at `http://127.0.0.1:5555` | `m5 view` |
|
|
104
|
+
| `m5 serve` | Start the MCP server over stdio (invoked by IDEs) | `m5 serve` |
|
|
105
|
+
| `m5 purge` | Cleanly remove `.m5/` index from project | `m5 purge` |
|
|
106
|
+
| `m5 scan` | Force full re-index of the repository | `m5 scan` |
|
|
107
|
+
| `m5 dump` | Export index bundle for CI / team sharing | `m5 dump` |
|
|
108
|
+
| `m5 pull` | Pull pre-computed team index from CI cache | `m5 pull https://ci.company.com/index.tar.gz` |
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 🖥️ Visual Graph Browser (`m5 view`)
|
|
113
|
+
|
|
114
|
+
Want to see what your AI agent sees? Run:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
m5 view
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Opens a fast, dark-mode browser interface at `http://127.0.0.1:5555`:
|
|
121
|
+
- **Search & Filter**: Find any function, method, or class across your repo with instant fuzzy search.
|
|
122
|
+
- **Live Code Inspection**: Read exact symbol bodies with line numbers and AST metadata.
|
|
123
|
+
- **Dependency Panels**: See direct callers, outgoing calls, and affected files on the side.
|
|
124
|
+
- **Zero External Server**: Powered by Python's built-in HTTP server, so it starts instantly without npm or heavy node packages.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## 🤖 Agent Instructions (CLAUDE.md / AGENTS.md / GEMINI.md)
|
|
129
|
+
|
|
130
|
+
To help subagents and command-line agents make the most of M5, paste this snippet into your project's `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`:
|
|
131
|
+
|
|
132
|
+
```markdown
|
|
133
|
+
<!-- M5 CONTEXT ENGINE START -->
|
|
134
|
+
## M5 Code Context & AST Knowledge Graph
|
|
135
|
+
This project uses M5 for instant AST code intelligence and dependency navigation.
|
|
136
|
+
Instead of repeatedly reading entire files or running multiple grep commands:
|
|
137
|
+
- Run `m5 trace "<query>"` to retrieve relevant symbol definitions, call hierarchies, and blast radius in 1 step.
|
|
138
|
+
- Run `m5 peek <symbol>` to view the exact implementation and callers of any function or class.
|
|
139
|
+
- Run `m5 callers <symbol>` or `m5 callees <symbol>` to navigate the call graph.
|
|
140
|
+
- Run `m5 diff-tests` to see tests affected by modified files.
|
|
141
|
+
<!-- M5 CONTEXT ENGINE END -->
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## 🌐 Supported Languages
|
|
147
|
+
|
|
148
|
+
M5 extracts full AST symbol trees and resolves cross-file call edges across:
|
|
149
|
+
|
|
150
|
+
- **Web & Backend**: Python, TypeScript, JavaScript, Go, Rust, Java, C++, C, C#, Ruby, PHP
|
|
151
|
+
- **Mobile & Modern**: Swift, Kotlin, Dart, Scala
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## 📄 License
|
|
156
|
+
|
|
157
|
+
MIT License. Free and open source for developers and teams.
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# M5 — AST Code Knowledge Graph for AI Coding Agents
|
|
2
|
+
|
|
3
|
+
When AI agents work on your codebase, they spend most of their time (and your tokens) doing clumsy discovery: grepping files one by one, wandering through directory listings, and trying to reconstruct call hierarchies in their head.
|
|
4
|
+
|
|
5
|
+
**M5 fixes that.** It parses your codebase with Tree-sitter into an embedded, zero-overhead SQLite knowledge graph (`.m5/local_graph.db`). When your agent asks a question, M5 returns the exact code, upstream callers, downstream dependencies, and blast radius in **one single call**.
|
|
6
|
+
|
|
7
|
+
- **100% Local**: No Docker, no heavy background daemons, no cloud dependency.
|
|
8
|
+
- **Sub-50ms Incremental Sync**: Watches your files and updates only what changed when you save.
|
|
9
|
+
- **Zero-Friction MCP Integration**: Works with Claude Code, Cursor, VS Code / Copilot, Gemini CLI, Antigravity, and Codex.
|
|
10
|
+
- **Interactive Browser UI**: Visualize your architecture and dependency chains at `http://127.0.0.1:5555`.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 🚀 Quickstart
|
|
15
|
+
|
|
16
|
+
### 1. Install M5
|
|
17
|
+
Install globally using `pip` or `pipx`:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install m5-context
|
|
21
|
+
# or with pipx:
|
|
22
|
+
pipx install m5-context
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### 2. Connect Your AI Agent
|
|
26
|
+
Run the interactive setup wizard to get clean, copy-pasteable MCP config snippets for your editor:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
m5 setup
|
|
30
|
+
```
|
|
31
|
+
*(Or specify your tool directly: `m5 setup claude`, `m5 setup cursor`, `m5 setup vscode`)*
|
|
32
|
+
|
|
33
|
+
Paste the provided JSON block into your editor's MCP configuration. We don't silently rewrite your system files behind your back — you stay in full control.
|
|
34
|
+
|
|
35
|
+
### 3. Build Your Project Index
|
|
36
|
+
Navigate to any project repository and build the graph:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
cd your-project
|
|
40
|
+
m5 build
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This scans your workspace and indexes all AST symbols and call edges into `.m5/local_graph.db` in under a second.
|
|
44
|
+
|
|
45
|
+
### 4. Keep It Fresh While You Code
|
|
46
|
+
Start the background watcher:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
m5 live
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Whenever you or your AI agent edits a file, M5 catches the change and updates the graph in $<50\text{ms}$.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 🔍 CLI Commands
|
|
57
|
+
|
|
58
|
+
| Command | What it does | Example |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `m5 setup` | Interactive manual setup wizard with exact MCP configs for your IDE | `m5 setup` or `m5 setup cursor` |
|
|
61
|
+
| `m5 build` | Scans workspace and builds AST knowledge graph into `.m5/` | `m5 build` |
|
|
62
|
+
| `m5 live` | Starts real-time file watcher (<50ms incremental sync on save) | `m5 live` |
|
|
63
|
+
| `m5 stats` | Shows index summary (files, AST symbols, call edges, DB size) | `m5 stats` |
|
|
64
|
+
| `m5 trace` | 1-shot surgical context: verbatim code + call flow + blast radius | `m5 trace "auth middleware token validation"` |
|
|
65
|
+
| `m5 peek` | View symbol definition & callers, or view line-numbered file | `m5 peek UserService` or `m5 peek src/auth.py` |
|
|
66
|
+
| `m5 find` | Search AST symbols by name, type, or pattern (FTS5 + B-tree) | `m5 find parse_jwt` |
|
|
67
|
+
| `m5 callers` | Find all functions and files calling a symbol | `m5 callers handle_request` |
|
|
68
|
+
| `m5 callees` | Find all functions called by a symbol | `m5 callees handle_request` |
|
|
69
|
+
| `m5 blast` | Multi-hop blast radius & affected files analysis before refactoring | `m5 blast DatabasePool --depth 2` |
|
|
70
|
+
| `m5 diff-tests` | Find test suites affected by modified files | `git diff --name-only \| m5 diff-tests --stdin` |
|
|
71
|
+
| `m5 view` | Open local browser visualizer at `http://127.0.0.1:5555` | `m5 view` |
|
|
72
|
+
| `m5 serve` | Start the MCP server over stdio (invoked by IDEs) | `m5 serve` |
|
|
73
|
+
| `m5 purge` | Cleanly remove `.m5/` index from project | `m5 purge` |
|
|
74
|
+
| `m5 scan` | Force full re-index of the repository | `m5 scan` |
|
|
75
|
+
| `m5 dump` | Export index bundle for CI / team sharing | `m5 dump` |
|
|
76
|
+
| `m5 pull` | Pull pre-computed team index from CI cache | `m5 pull https://ci.company.com/index.tar.gz` |
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 🖥️ Visual Graph Browser (`m5 view`)
|
|
81
|
+
|
|
82
|
+
Want to see what your AI agent sees? Run:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
m5 view
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Opens a fast, dark-mode browser interface at `http://127.0.0.1:5555`:
|
|
89
|
+
- **Search & Filter**: Find any function, method, or class across your repo with instant fuzzy search.
|
|
90
|
+
- **Live Code Inspection**: Read exact symbol bodies with line numbers and AST metadata.
|
|
91
|
+
- **Dependency Panels**: See direct callers, outgoing calls, and affected files on the side.
|
|
92
|
+
- **Zero External Server**: Powered by Python's built-in HTTP server, so it starts instantly without npm or heavy node packages.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 🤖 Agent Instructions (CLAUDE.md / AGENTS.md / GEMINI.md)
|
|
97
|
+
|
|
98
|
+
To help subagents and command-line agents make the most of M5, paste this snippet into your project's `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`:
|
|
99
|
+
|
|
100
|
+
```markdown
|
|
101
|
+
<!-- M5 CONTEXT ENGINE START -->
|
|
102
|
+
## M5 Code Context & AST Knowledge Graph
|
|
103
|
+
This project uses M5 for instant AST code intelligence and dependency navigation.
|
|
104
|
+
Instead of repeatedly reading entire files or running multiple grep commands:
|
|
105
|
+
- Run `m5 trace "<query>"` to retrieve relevant symbol definitions, call hierarchies, and blast radius in 1 step.
|
|
106
|
+
- Run `m5 peek <symbol>` to view the exact implementation and callers of any function or class.
|
|
107
|
+
- Run `m5 callers <symbol>` or `m5 callees <symbol>` to navigate the call graph.
|
|
108
|
+
- Run `m5 diff-tests` to see tests affected by modified files.
|
|
109
|
+
<!-- M5 CONTEXT ENGINE END -->
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## 🌐 Supported Languages
|
|
115
|
+
|
|
116
|
+
M5 extracts full AST symbol trees and resolves cross-file call edges across:
|
|
117
|
+
|
|
118
|
+
- **Web & Backend**: Python, TypeScript, JavaScript, Go, Rust, Java, C++, C, C#, Ruby, PHP
|
|
119
|
+
- **Mobile & Modern**: Swift, Kotlin, Dart, Scala
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 📄 License
|
|
124
|
+
|
|
125
|
+
MIT License. Free and open source for developers and teams.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: m5-engine
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Intelligent, zero-overhead AST code context and dependency graph engine for AI coding agents,saving LLM token costs.
|
|
5
|
+
Author-email: Aman <lazyserp@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/m5-context-engine/m5
|
|
8
|
+
Project-URL: Documentation, https://github.com/m5-context-engine/m5#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/m5-context-engine/m5.git
|
|
10
|
+
Project-URL: Issues, https://github.com/m5-context-engine/m5/issues
|
|
11
|
+
Keywords: mcp,model-context-protocol,ast,code-graph,developer-tools,ai-agents,cursor,claude-code,copilot
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Requires-Python: >=3.9
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
Requires-Dist: tree-sitter>=0.20.0
|
|
25
|
+
Requires-Dist: pydantic>=2.0.0
|
|
26
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
27
|
+
Provides-Extra: enterprise
|
|
28
|
+
Requires-Dist: fastapi>=0.100.0; extra == "enterprise"
|
|
29
|
+
Requires-Dist: uvicorn>=0.22.0; extra == "enterprise"
|
|
30
|
+
Requires-Dist: qdrant-client>=1.6.0; extra == "enterprise"
|
|
31
|
+
Requires-Dist: fastembed>=0.2.0; extra == "enterprise"
|
|
32
|
+
|
|
33
|
+
# M5 — AST Code Knowledge Graph for AI Coding Agents
|
|
34
|
+
|
|
35
|
+
When AI agents work on your codebase, they spend most of their time (and your tokens) doing clumsy discovery: grepping files one by one, wandering through directory listings, and trying to reconstruct call hierarchies in their head.
|
|
36
|
+
|
|
37
|
+
**M5 fixes that.** It parses your codebase with Tree-sitter into an embedded, zero-overhead SQLite knowledge graph (`.m5/local_graph.db`). When your agent asks a question, M5 returns the exact code, upstream callers, downstream dependencies, and blast radius in **one single call**.
|
|
38
|
+
|
|
39
|
+
- **100% Local**: No Docker, no heavy background daemons, no cloud dependency.
|
|
40
|
+
- **Sub-50ms Incremental Sync**: Watches your files and updates only what changed when you save.
|
|
41
|
+
- **Zero-Friction MCP Integration**: Works with Claude Code, Cursor, VS Code / Copilot, Gemini CLI, Antigravity, and Codex.
|
|
42
|
+
- **Interactive Browser UI**: Visualize your architecture and dependency chains at `http://127.0.0.1:5555`.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 🚀 Quickstart
|
|
47
|
+
|
|
48
|
+
### 1. Install M5
|
|
49
|
+
Install globally using `pip` or `pipx`:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install m5-context
|
|
53
|
+
# or with pipx:
|
|
54
|
+
pipx install m5-context
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### 2. Connect Your AI Agent
|
|
58
|
+
Run the interactive setup wizard to get clean, copy-pasteable MCP config snippets for your editor:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
m5 setup
|
|
62
|
+
```
|
|
63
|
+
*(Or specify your tool directly: `m5 setup claude`, `m5 setup cursor`, `m5 setup vscode`)*
|
|
64
|
+
|
|
65
|
+
Paste the provided JSON block into your editor's MCP configuration. We don't silently rewrite your system files behind your back — you stay in full control.
|
|
66
|
+
|
|
67
|
+
### 3. Build Your Project Index
|
|
68
|
+
Navigate to any project repository and build the graph:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
cd your-project
|
|
72
|
+
m5 build
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
This scans your workspace and indexes all AST symbols and call edges into `.m5/local_graph.db` in under a second.
|
|
76
|
+
|
|
77
|
+
### 4. Keep It Fresh While You Code
|
|
78
|
+
Start the background watcher:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
m5 live
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Whenever you or your AI agent edits a file, M5 catches the change and updates the graph in $<50\text{ms}$.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 🔍 CLI Commands
|
|
89
|
+
|
|
90
|
+
| Command | What it does | Example |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `m5 setup` | Interactive manual setup wizard with exact MCP configs for your IDE | `m5 setup` or `m5 setup cursor` |
|
|
93
|
+
| `m5 build` | Scans workspace and builds AST knowledge graph into `.m5/` | `m5 build` |
|
|
94
|
+
| `m5 live` | Starts real-time file watcher (<50ms incremental sync on save) | `m5 live` |
|
|
95
|
+
| `m5 stats` | Shows index summary (files, AST symbols, call edges, DB size) | `m5 stats` |
|
|
96
|
+
| `m5 trace` | 1-shot surgical context: verbatim code + call flow + blast radius | `m5 trace "auth middleware token validation"` |
|
|
97
|
+
| `m5 peek` | View symbol definition & callers, or view line-numbered file | `m5 peek UserService` or `m5 peek src/auth.py` |
|
|
98
|
+
| `m5 find` | Search AST symbols by name, type, or pattern (FTS5 + B-tree) | `m5 find parse_jwt` |
|
|
99
|
+
| `m5 callers` | Find all functions and files calling a symbol | `m5 callers handle_request` |
|
|
100
|
+
| `m5 callees` | Find all functions called by a symbol | `m5 callees handle_request` |
|
|
101
|
+
| `m5 blast` | Multi-hop blast radius & affected files analysis before refactoring | `m5 blast DatabasePool --depth 2` |
|
|
102
|
+
| `m5 diff-tests` | Find test suites affected by modified files | `git diff --name-only \| m5 diff-tests --stdin` |
|
|
103
|
+
| `m5 view` | Open local browser visualizer at `http://127.0.0.1:5555` | `m5 view` |
|
|
104
|
+
| `m5 serve` | Start the MCP server over stdio (invoked by IDEs) | `m5 serve` |
|
|
105
|
+
| `m5 purge` | Cleanly remove `.m5/` index from project | `m5 purge` |
|
|
106
|
+
| `m5 scan` | Force full re-index of the repository | `m5 scan` |
|
|
107
|
+
| `m5 dump` | Export index bundle for CI / team sharing | `m5 dump` |
|
|
108
|
+
| `m5 pull` | Pull pre-computed team index from CI cache | `m5 pull https://ci.company.com/index.tar.gz` |
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## 🖥️ Visual Graph Browser (`m5 view`)
|
|
113
|
+
|
|
114
|
+
Want to see what your AI agent sees? Run:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
m5 view
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Opens a fast, dark-mode browser interface at `http://127.0.0.1:5555`:
|
|
121
|
+
- **Search & Filter**: Find any function, method, or class across your repo with instant fuzzy search.
|
|
122
|
+
- **Live Code Inspection**: Read exact symbol bodies with line numbers and AST metadata.
|
|
123
|
+
- **Dependency Panels**: See direct callers, outgoing calls, and affected files on the side.
|
|
124
|
+
- **Zero External Server**: Powered by Python's built-in HTTP server, so it starts instantly without npm or heavy node packages.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## 🤖 Agent Instructions (CLAUDE.md / AGENTS.md / GEMINI.md)
|
|
129
|
+
|
|
130
|
+
To help subagents and command-line agents make the most of M5, paste this snippet into your project's `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`:
|
|
131
|
+
|
|
132
|
+
```markdown
|
|
133
|
+
<!-- M5 CONTEXT ENGINE START -->
|
|
134
|
+
## M5 Code Context & AST Knowledge Graph
|
|
135
|
+
This project uses M5 for instant AST code intelligence and dependency navigation.
|
|
136
|
+
Instead of repeatedly reading entire files or running multiple grep commands:
|
|
137
|
+
- Run `m5 trace "<query>"` to retrieve relevant symbol definitions, call hierarchies, and blast radius in 1 step.
|
|
138
|
+
- Run `m5 peek <symbol>` to view the exact implementation and callers of any function or class.
|
|
139
|
+
- Run `m5 callers <symbol>` or `m5 callees <symbol>` to navigate the call graph.
|
|
140
|
+
- Run `m5 diff-tests` to see tests affected by modified files.
|
|
141
|
+
<!-- M5 CONTEXT ENGINE END -->
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## 🌐 Supported Languages
|
|
147
|
+
|
|
148
|
+
M5 extracts full AST symbol trees and resolves cross-file call edges across:
|
|
149
|
+
|
|
150
|
+
- **Web & Backend**: Python, TypeScript, JavaScript, Go, Rust, Java, C++, C, C#, Ruby, PHP
|
|
151
|
+
- **Mobile & Modern**: Swift, Kotlin, Dart, Scala
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## 📄 License
|
|
156
|
+
|
|
157
|
+
MIT License. Free and open source for developers and teams.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
m5_engine.egg-info/PKG-INFO
|
|
4
|
+
m5_engine.egg-info/SOURCES.txt
|
|
5
|
+
m5_engine.egg-info/dependency_links.txt
|
|
6
|
+
m5_engine.egg-info/entry_points.txt
|
|
7
|
+
m5_engine.egg-info/requires.txt
|
|
8
|
+
m5_engine.egg-info/top_level.txt
|
|
9
|
+
src/__init__.py
|
|
10
|
+
src/auth.py
|
|
11
|
+
src/config.py
|
|
12
|
+
src/logger.py
|
|
13
|
+
src/main.py
|
|
14
|
+
src/mcp_server.py
|
|
15
|
+
src/server.py
|
|
16
|
+
src/api/webhooks.py
|
|
17
|
+
src/audit/__init__.py
|
|
18
|
+
src/audit/telemetry.py
|
|
19
|
+
src/cli/__init__.py
|
|
20
|
+
src/cli/installer.py
|
|
21
|
+
src/cli/main.py
|
|
22
|
+
src/cli/setup_guide.py
|
|
23
|
+
src/cli/sync.py
|
|
24
|
+
src/cli/visual_server.py
|
|
25
|
+
src/context/__init__.py
|
|
26
|
+
src/context/context_engine.py
|
|
27
|
+
src/indexer/file_watcher.py
|
|
28
|
+
src/indexer/git_manager.py
|
|
29
|
+
src/indexer/progressive_indexer.py
|
|
30
|
+
src/parser/ast_parser.py
|
|
31
|
+
src/parser/customizations.py
|
|
32
|
+
src/storage/local_db.py
|
|
33
|
+
src/tools/__init__.py
|
|
34
|
+
src/tools/dependency_graph.py
|
|
35
|
+
src/tools/hybrid_search.py
|
|
36
|
+
src/tools/line_reader.py
|
|
37
|
+
src/tools/multi_repo_graph.py
|
|
38
|
+
src/tools/test_impact.py
|
|
39
|
+
src/tools/vector_search.py
|
|
40
|
+
test/test_ast_parser.py
|
|
41
|
+
test/test_customizations.py
|
|
42
|
+
test/test_dependency_graph.py
|
|
43
|
+
test/test_git_manager.py
|
|
44
|
+
test/test_hybrid_search.py
|
|
45
|
+
test/test_mcp_http.py
|
|
46
|
+
test/test_mcp_server.py
|
|
47
|
+
test/test_multitenancy.py
|
|
48
|
+
test/test_progressive_indexer.py
|
|
49
|
+
test/test_telemetry.py
|
|
50
|
+
test/test_tenant_isolation.py
|
|
51
|
+
test/test_vector_search.py
|
|
52
|
+
test/test_webhook_delta.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
src
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "m5-engine"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Intelligent, zero-overhead AST code context and dependency graph engine for AI coding agents,saving LLM token costs."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "Aman", email = "lazyserp@gmail.com" }
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"mcp", "model-context-protocol", "ast", "code-graph",
|
|
17
|
+
"developer-tools", "ai-agents", "cursor", "claude-code", "copilot"
|
|
18
|
+
]
|
|
19
|
+
classifiers = [
|
|
20
|
+
"Development Status :: 4 - Beta",
|
|
21
|
+
"Intended Audience :: Developers",
|
|
22
|
+
"Topic :: Software Development :: Code Generators",
|
|
23
|
+
"Topic :: Software Development :: Libraries",
|
|
24
|
+
"License :: OSI Approved :: MIT License",
|
|
25
|
+
"Programming Language :: Python :: 3",
|
|
26
|
+
"Programming Language :: Python :: 3.9",
|
|
27
|
+
"Programming Language :: Python :: 3.10",
|
|
28
|
+
"Programming Language :: Python :: 3.11",
|
|
29
|
+
"Programming Language :: Python :: 3.12",
|
|
30
|
+
]
|
|
31
|
+
dependencies = [
|
|
32
|
+
"tree-sitter>=0.20.0",
|
|
33
|
+
"pydantic>=2.0.0",
|
|
34
|
+
"python-dotenv>=1.0.0"
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
enterprise = [
|
|
39
|
+
"fastapi>=0.100.0",
|
|
40
|
+
"uvicorn>=0.22.0",
|
|
41
|
+
"qdrant-client>=1.6.0",
|
|
42
|
+
"fastembed>=0.2.0"
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[project.scripts]
|
|
46
|
+
m5 = "src.cli.main:cli_entrypoint"
|
|
47
|
+
|
|
48
|
+
[tool.setuptools.packages.find]
|
|
49
|
+
where = ["."]
|
|
50
|
+
include = ["src*"]
|
|
51
|
+
|
|
52
|
+
[project.urls]
|
|
53
|
+
Homepage = "https://github.com/m5-context-engine/m5"
|
|
54
|
+
Documentation = "https://github.com/m5-context-engine/m5#readme"
|
|
55
|
+
Repository = "https://github.com/m5-context-engine/m5.git"
|
|
56
|
+
Issues = "https://github.com/m5-context-engine/m5/issues"
|
|
File without changes
|