Dependency Context

依赖上下文

作者： @darianb

MCP 服务和命令行工具，为 AI 助手提供对项目依赖文档的上下文访问能力，从而让它们能够更准确地回答有关代码库所用库和框架的问题。

配置

指定要索引哪些依赖的推荐方式，是在项目根目录中创建自定义的 dependency-context.json 文件。这样可以：

• 只索引你正在使用且需要帮助的依赖
• 限制依赖数量，以提升索引速度
• 将搜索结果聚焦在最重要的库上

在项目根目录中创建一个 dependency-context.json 文件，格式如下：

{
  "express": "^4.17.1",
  "axios": "1.0.0"
}

如果不存在 dependency-context.json 文件，Dependency Context 会退而扫描 package.json 或 requirements.txt。

快速入门

选项 1：将 MCP 与 AI 集成（推荐 Cursor 用户使用）

1. 将 MCP 配置添加到编辑器中（推荐 Cursor）：

{
  "mcpServers": {
    "dependency-context": {
      "command": "npx",
      "args": ["-y", "--package=dependency-context", "dependency-context"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN_HERE", // Optional but recommended
        "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // Optional, default shown
        "DEBUG": "false", // Optional, default shown
        "MIN_CHUNK_SIZE": "800", // Optional, default shown
        "MAX_CHUNK_SIZE": "8000", // Optional, default shown
        "CHUNKS_RETURNED": "5" // Optional, default shown
      }
    }
  }
}

2. 在编辑器中启用 MCP

3. 提示 AI 初始化 dependency-context。请确保处于“Agent”模式。

Can you initialize dependency-context?

4. 像平常一样向 AI 提示。相关时，它会自动调用 dependency-context

选项 2：直接下载文档（无需向量数据库）

如果你只想下载并浏览依赖文档，而不使用向量搜索：

1. 安装 dependency-context：

npm install -g dependency-context

2. 下载项目的文档：

# From your project directory
dependency-context download

# Or specify a different project path
dependency-context download /path/to/your/project

3. 在项目中的 dependency-context 文件夹里找到文档：

# Explore the documentation
cd dependency-context
ls

每个依赖都有自己的文件夹，其中包含其代码库中的所有 Markdown 文档。

MCP 工具

Dependency Context 通过 MCP 接口提供两个主要工具：

1. InitializeDependencyIndex

分析项目的依赖，并为其文档创建可搜索的索引。

{
  "capability": "InitializeDependencyIndex",
  "parameters": {
    "project_path": "/path/to/your/project",
    "env_vars": {
      "GITHUB_TOKEN": "your_github_token", // Optional but recommended
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // Optional, default shown
      "DEBUG": "true", // Optional
      "MIN_CHUNK_SIZE": "800", // Optional, default shown
      "MAX_CHUNK_SIZE": "8000" // Optional, default shown
    }
  }
}

此功能：

• 检查自定义的 dependencies.json 文件（推荐）
• 如果不存在自定义文件，则退而扫描 package.json 或 requirements.txt
• 查找每个依赖对应的 GitHub 仓库
• 克隆仓库并提取 Markdown 文档
• 创建向量嵌入，以支持语义搜索

2. searchDependencyDocs

对已索引的依赖文档执行语义搜索。

{
  "capability": "searchDependencyDocs",
  "parameters": {
    "project_path": "/path/to/your/project",
    "query": "How do I handle authentication?",
    "repository_context": "express", // Optional: limit to a specific dependency
    "env_vars": {
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2",
      "CHUNKS_RETURNED": "5" // Optional, default shown
    }
  }
}

返回：

• 与查询最相关的文档片段
• 来源信息（仓库、文件路径）
• 每条结果的相似度分数

架构

Dependency Context 采用模块化 TypeScript 架构构建：

• 核心组件：

  • 解析器：从 package.json 和 requirements.txt 中提取依赖
  • 仓库发现：利用注册表元数据查找 GitHub 仓库
  • 文档获取：克隆仓库并提取文档
  • 向量存储：生成嵌入并支持语义搜索
  • MCP 服务：为 AI 工具提供标准化接口

• 主要库：

  • fastmcp：MCP 协议实现
  • @xenova/transformers：用于生成向量的本地嵌入模型
  • simple-git：用于仓库操作的 Git 客户端
  • axios：用于 API 请求的 HTTP 客户端
  • fs-extra：增强型文件系统操作
  • dotenv：环境变量管理

测试

单元测试

运行测试套件：

npm test

手动测试

手动测试时，请按以下步骤操作：

1. 设置测试项目

mkdir test-project
cd test-project

# Create a custom dependencies.json file (recommended approach)
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > dependencies.json

# Alternatively, you can use standard dependency files:

# For Node.js projects
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > package.json

# For Python projects
echo 'requests==2.26.0
numpy>=1.20.0' > requirements.txt

2. 使用 fastmcp dev 测试 dependency-context

# Build and make the CLI executable
cd /path/to/dependency-context
npx fastmcp dev src/index.ts

# Initialize and index dependencies (from your test project directory)
tool(InitializeDependencyIndex)

# Search for information in the indexed dependencies
tool(searchDependencyDocs)


## Troubleshooting

### GitHub API Rate Limits

If you encounter "API rate limit exceeded" errors:

1. Create a GitHub personal access token at https://github.com/settings/tokens
2. Set it as the `GITHUB_TOKEN` environment variable:
   ```bash
   export GITHUB_TOKEN=your_token_here

3. 或将其添加到 .env 文件中：

   # Optional but recommended for higher API rate limits
   GITHUB_TOKEN=your_token_here
   
   # Optional settings with defaults shown below
   MIN_CHUNK_SIZE=800
   MAX_CHUNK_SIZE=8000
   CHUNKS_RETURNED=5
   

搜索结果为空

如果搜索返回空结果：

1. 确认索引过程已成功完成
2. 检查控制台输出中是否有错误消息
3. 确认搜索查询与已索引的依赖相关
4. 尝试更通用的查询，查看是否能返回结果

权限问题

如果访问项目目录时遇到权限错误：

1. 确保服务对项目目录具有读写权限
2. 检查临时目录是否可访问
3. 使用适当的权限运行服务

开发

# Clone the repository
git clone https://github.com/yourusername/dependency-context.git

# Install dependencies
cd dependency-context
npm install

# Run MCP server locally with fastmcp dev
npx fastmcp dev src/index.ts

# Test CLI download command
node src/index.js download ./test-project

项目待办事项

高优先级

• 搭建基本项目结构并配置依赖项
• 实现用于解析 package.json 和 requirements.txt 的依赖项解析器
• 创建 GitHub 仓库发现功能
• 构建文档获取和 Markdown 处理功能
• 实现向量存储的创建和索引
• 设置用于语义搜索的 MCP 端点
• 支持通过多个渠道（系统、项目、MCP 参数）设置环境变量
• 为函数添加分块大小和 top-k 返回数量参数
• 添加用于下载原始文档的 CLI 模式
• 为 GitHub API 添加完善的错误处理和重试机制

中优先级

• 支持更多包管理器（Maven、Go、Rust）
• 为耗时较长的索引操作添加进度报告
• 改进分块算法，更好地遵循 Markdown 结构
• 支持非 GitHub 仓库（GitLab、Bitbucket）

低优先级

• 编写全面的文档

未来增强

• 更多包管理器：支持 pom.xml、go.mod 和其他依赖项格式（注意：已支持自定义 dependencies.json，推荐使用此方式）
• 增量索引：避免重新处理未更改的仓库
• 可配置分块：提供自定义的文档拆分策略
• 替代模型：支持不同的嵌入模型
• 缓存层：提升频繁访问文档时的性能

许可证

Dependency Context 采用 MIT License with Commons Clause 许可。这意味着你可以：

✅ 允许：

• 将 Dependency Context 用于任何用途（个人、商业、学术）
• 修改代码
• 分发副本
• 创建并销售使用 Dependency Context 构建的产品

❌ 不允许：

• 出售 Dependency Context 本身
• 将 Dependency Context 作为托管服务提供
• 基于 Dependency Context 创建竞争产品

有关完整的许可证文本和许可详情，请参阅 LICENSE 文件。

版权所有 © 2024 DarianB