shubham0086/Agent-Context

# Agent-Context **给你的 agent 关于代码库所需的 200 个 token，而不是 8000 个 token 的噪音。** Agent-Context 会遍历任何项目，构建一个依赖关系图，并准确地告诉 agent 哪些文件依赖于给定的文件，以及该文件依赖于哪些文件。这种影响范围极其紧凑，刚好能塞进一个 prompt 中。 从 18 个月的 Agency OS 生产环境中提炼而来。 [](LICENSE) [](package.json) []() ## 快速开始 ``` git clone https://github.com/shubham0086/Agent-Context cd Agent-Context # 映射任何 repo 的 dependency graph node demo/graph.js . # 显示特定文件的 blast radius node demo/blast-radius.js src/Graphify.js . ``` 无需安装。零外部依赖。 ## MCP Server (在你的 AI IDE 中使用) Agent-Context 也作为 **MCP server** 提供，因此 AI IDE (Claude Code, Cursor) 可以直接调用它的影响范围。它公开了两个工具： - `blast_radius(file, root?)` ：某个文件的依赖项和被依赖项 - `graph_summary(root?)` ：文件/边的数量，用于确认代码库是否可分析 它是 [The Machine OS](https://github.com/shubham0086/the-machine-os) 的 **code-graph 核心**： `/code-review` 和 `/tech-debt` 技能会调用它，以查看某项更改在 diff 之外实际影响了什么。 ### 前置条件 你的 PATH 中需要有 [Node.js](https://nodejs.org) 18+（服务器通过 `npx` 运行）。该服务器添加了一个依赖项，即官方的 `@modelcontextprotocol/sdk`；核心的 `GraphifyClient` 导入保持零依赖。 ### 选项 A（推荐）：通过 The Machine OS 插件安装 如果你使用 Claude Code，则无需手动配置。安装工具插件后，技能会自动调用此服务器： ``` /plugin marketplace add shubham0086/the-machine-os /plugin install ai-engineering-tools@machine-os /reload-plugins ``` ### 选项 B：在 Claude Desktop 中安装（一键扩展） Claude Desktop 将 MCP server 作为 **`.mcpb` 扩展**进行安装 —— 无需编辑 JSON。使用 [mcpb](https://github.com/anthropics/mcpb) 打包器构建一次 bundle，然后安装它： ``` npm install -g @anthropic-ai/mcpb # one-time: the packager npm install --omit=dev # production dep only (@modelcontextprotocol/sdk) mcpb pack # -> machine-os-code-graph.mcpb ``` 在 Claude Desktop 中：**Settings → Extensions → Install Extension →** 选择 `.mcpb` 文件，然后选择你的 **Workspace root**（即工具可以分析的代码库）。随后，`blast_radius` 和 `graph_summary` 工具就会在 Claude 中出现。你选择的 workspace 目录就是安全锚点 —— 分析是只读的，且无法脱离该目录。 ### 选项 C：手动将其接入任何 MCP client 对于 Cursor 或独立的 client，请将以下内容添加到你的 MCP 配置中（例如 `.cursor/mcp.json` 或 Claude Code 的 `mcp` 设置中）： ``` { "mcpServers": { "code-graph": { "command": "npx", "args": ["-y", "github:shubham0086/agent-context"] } } } ``` 或者直接通过 stdio 运行它以进行测试： ``` npx -y github:shubham0086/agent-context ``` ### 安全性 该服务器是 **只读的**，并将分析限制在 workspace 内：每次调用指定的 `root` 无法逃逸出 `GRAPHIFY_ROOT`/cwd，并且每次调用都有时间限制（`GRAPHIFY_TIMEOUT_MS`，默认为 15 秒）。 有关路径遍历防御，请参阅下方的 [安全与沙箱化](#security--sandboxing-mcp)。 ## 它的功能 1. **遍历你的项目**，跳过 `node_modules`、`.git`、`dist`、`venv` 及类似的噪音 2. **提取 import**（支持 JS, TS, JSX, TSX, Python, Go） 3. **构建关系图**：节点是文件，边是依赖关系 4. **解答影响范围**：触碰了 `auth.js` —— 还有什么会出问题？ 5. **为 LLM 注入进行格式化**：一段紧凑的 context 字符串，供 agent 在采取行动前读取 ### Context 字符串（被注入到 prompt 中的内容） ``` ### 为 [src/auth.js] GRAPHIFY STRUCTURAL CONTEXT - Dependencies (what this file uses): src/db.js, src/utils/crypto.js - Dependents (what relies on this file): src/routes/login.js, src/routes/signup.js, src/middleware/guard.js Rule: If you modify this file, be aware of the blast radius affecting its dependents. ``` 在编辑 `auth.js` 之前阅读了此内容的 agent 会知道，它需要检查 3 个下游文件。如果 agent 没看这个，就会悄无声息地破坏它们。 ## API ### `new GraphifyClient(projectRoot)` ``` import { GraphifyClient } from 'agent-context'; const client = new GraphifyClient('./my-project'); ``` ### `buildGraph()` / `getGraphSummary()` ``` const summary = await client.getGraphSummary(); // { nodeCount: 42, edgeCount: 87, nodes: {...}, edges: [...] } ``` ### `queryNeighbors(filePath)` ``` const { target, dependents, dependencies } = await client.queryNeighbors('src/auth.js'); // dependents: files that import auth.js (will break if you change it) // dependencies: files that auth.js imports (must exist for auth.js to work) ``` ### `getContextString(filePath)` ``` const context = await client.getContextString('src/auth.js'); // Returns compact LLM-ready string, or '' if file has no tracked neighbors ``` ## 支持的语言 | 语言 | Import 检测 | |----------|-----------------| | JavaScript / Node.js | `require()` 和 `import from` | | TypeScript | `import from` | | JSX / TSX | `import from` | | Python | `import` 和 `from X import` | | Go | `import "..."` | ## 安全与沙箱化 (MCP) 在通过 Model Context Protocol (MCP) 服务器将工具上下文公开给 LLM 时，请验证查询路径以降低注入风险： - **规范化路径**：确保在遍历依赖关系之前，所有路径都已规范化（移除 `../` 序列）。 - **强制执行沙箱化**：将文件与加入白名单的 workspace 根目录沙箱进行匹配，以防止路径遍历 (CVE-2025-53110) 或符号链接绕过 (CVE-2025-53109)。 ## 适用场景 ``` AI-systems-evolution ← start here (rung 03: agent needs context) | └─► agentic-patterns ← Pattern 04 (graph-based agent context) | └─► Agent-Context ← THIS REPO (the runnable dependency graph) ``` 有关在生产环境中使用 Graphify 的完整编排技术栈：请参阅 [agentkernel](https://github.com/shubham0086/agentkernel)。 **理论伴侣：** [Pattern 04: GraphDB for Agent Context](https://github.com/shubham0086/agentic-patterns/blob/main/docs/04-graphdb-for-agent-context.md)

标签：AI辅助编程, GNU通用公共许可证, MCP, MITM代理, Node.js, SOC Prime, 代码分析, 依赖图, 凭证管理, 开发工具, 数据可视化, 日志审计, 自定义脚本, 逆向工具