AI导哈

依赖文档索引工具

一个为AI助手提供项目依赖文档上下文的MCP服务器和命令行工具，帮助开发者更准确地获取代码库中使用的库和框架信息。

  • by Dsinghbailey
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 dsinghbailey/dependency-context

使用说明

依赖关系上下文

靠近 @达里安

MCP服务器和命令行工具，为AI助手提供对项目依赖性文档的上下文访问，从而能够更准确地响应代码库中使用的库和框架。

配置

建议通过创建自定义来指定要索引的依赖项 dependency-context.json 项目根目录中的文件。这使您能够：

  • 只索引您正在积极使用并需要帮助的依赖关系
  • 通过限制依赖关系的数量来提高索引速度
  • 将搜索结果集中在最重要的库上

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

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

如果a dependency-context.json 文件不存在，依赖关系上下文回退到扫描 package.json 或 requirements.txt.

快速开始

选项1：使用带有AI集成的MCP（建议用于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
      }
    }
  }
}

  1. 在编辑器中启用MCP

  2. 提示AI初始化依赖关系上下文。确保您处于“代理”模式。

Can you initialize dependency-context?
  1. 像往常一样提示AI。它会在相关时自动拉入依赖上下文

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

如果您只想下载并浏览依赖关系文档而不进行矢量搜索：

  1. 安装依赖关系上下文：
npm install -g dependency-context
  1. 下载项目文档：
# From your project directory
dependency-context download

# Or specify a different project path
dependency-context download /path/to/your/project
  1. 在 dependency-context 项目中的文件夹：
# Explore the documentation
cd dependency-context
ls

每个依赖项都有自己的文件夹，其中包含其存储库中的所有markdown文档。

MCP工具

依赖上下文通过其MCP接口提供了两个主要工具：

1.初始化依赖索引

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

{
  "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.搜索DependencyDocs

对索引依赖关系文档执行语义搜索。

{
  "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
    }
  }
}

退货：

  • 与您的查询匹配的最相关文档块
  • 源信息（存储库、文件路径）
  • 每个结果的相似性得分

建筑

依赖上下文是用模块化的TypeScript架构构建的：

  • 核心组件:

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

  • 关键库:

    • fastmcp：MCP协议实施
    • @xenova/变压器：用于矢量创建的本地嵌入模型
    • 简单git：用于存储库操作的Git客户端
    • 轴：API请求的HTTP客户端
    • fs额外：增强的文件系统操作
    • 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
  1. 使用fastmcp-dev测试依赖关系上下文
# 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

  1. 或者将其添加到您的 .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

项目待办事项列表

高优先级

  • [x] 设置基本项目结构和依赖关系
  • [x] 为package.json和requirements.txt实现依赖解析器
  • [x] 创建GitHub存储库发现功能
  • [x] 构建文档获取和降价处理
  • [x] 实现矢量存储创建和索引
  • [x] 设置MCP端点进行语义搜索
  • [x] 通过多种渠道（系统、项目、MCP参数）添加环境变量支持
  • [x] 为函数添加块大小和top-k返回值的参数
  • [x] 添加CLI模式以下载原始文档
  • []为GitHub API添加正确的错误处理和重试机制

中优先级

  • []支持其他包管理器（Maven、Go、Rust）
  • []为长时间运行的索引操作添加进度报告
  • []增强分块算法，更好地尊重Markdown结构
  • []支持非GitHub存储库（GitLab、Bitbucket）

低优先级

  • [x] 创建全面的文档

未来的增强功能

  • 附加包管理器：支持pom.xml、go.mod和其他依赖格式（注意：自定义dependencies.json已作为推荐方法得到支持）
  • 增量索引：避免重新处理未更改的存储库
  • 可配置分块：文档拆分的自定义策略
  • 模型：支持不同的嵌入模型
  • 缓存层：提高了频繁访问文档的性能

许可证

依赖上下文根据带有Commons条款的MIT许可证进行许可。这意味着您可以：

✅ 允许：

  • 将依赖上下文用于任何目的（个人、商业、学术）
  • 修改代码
  • 分发副本
  • 创建和销售使用依赖上下文构建的产品

❌ 不允许：

  • 出售依赖关系上下文本身
  • 将依赖关系上下文作为托管服务提供
  • 基于依赖上下文创建竞争产品

请参阅 许可证 文件以获取完整的许可文本和许可详细信息。

版权所有©2024 DarianB

相关 MCP