星战科技xingzhan.cloud
返回市场
依赖上下文

依赖上下文

作者：Dsinghbailey2 星标更新：2025-05-07
安装使用来源：spider==github.com

项目介绍

依赖上下文

作者：@darianb

一个MCP服务器和命令行工具，提供AI助手对项目依赖文档的上下文访问，使关于代码库中使用的库和框架的回答更加准确。

配置

推荐的方式是通过在项目根目录创建自定义的dependency-context.json文件来指定要索引的依赖项。这允许您：

  • 只索引正在使用且需要帮助的依赖项
  • 通过限制依赖项的数量提高索引速度
  • 将搜索结果集中在最重要的库上

在项目根目录创建一个具有以下格式的dependency-context.json文件：

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

如果不存在dependency-context.json文件，依赖上下文会回退到扫描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", // 可选但推荐
        "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // 可选，默认值显示
        "DEBUG": "false", // 可选，默认值显示
        "MIN_CHUNK_SIZE": "800", // 可选，默认值显示
        "MAX_CHUNK_SIZE": "8000", // 可选，默认值显示
        "CHUNKS_RETURNED": "5" // 可选，默认值显示
      }
    }
  }
}

  1. 在编辑器中启用MCP

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

你能初始化依赖上下文吗？
  1. 像平常一样提示AI。当相关内容出现时，它会自动拉取依赖上下文。

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

如果您希望仅下载并浏览依赖文档而不进行向量搜索：

  1. 安装依赖上下文：
npm install -g dependency-context
  1. 下载项目的文档：
# 从您的项目目录
dependency-context download

# 或指定不同的项目路径
dependency-context download /path/to/your/project
  1. 在项目的dependency-context文件夹中找到文档：
# 浏览文档
cd dependency-context
ls

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

MCP工具

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

1. 初始化依赖索引

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

{
  "capability": "InitializeDependencyIndex",
  "parameters": {
    "project_path": "/path/to/your/project",
    "env_vars": {
      "GITHUB_TOKEN": "your_github_token", // 可选但推荐
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // 可选，默认值显示
      "DEBUG": "true", // 可选
      "MIN_CHUNK_SIZE": "800", // 可选，默认值显示
      "MAX_CHUNK_SIZE": "8000" // 可选，默认值显示
    }
  }
}

此功能：

  • 检查自定义的dependencies.json文件（推荐）
  • 如果没有自定义文件，则回退到扫描package.json或requirements.txt
  • 查找每个依赖项的GitHub存储库
  • 克隆存储库并提取Markdown文档
  • 创建向量嵌入以实现语义搜索

2. 搜索依赖文档

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

{
  "capability": "searchDependencyDocs",
  "parameters": {
    "project_path": "/path/to/your/project",
    "query": "如何处理身份验证？",
    "repository_context": "express", // 可选：限制到特定依赖项
    "env_vars": {
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2",
      "CHUNKS_RETURNED": "5" // 可选，默认值显示
    }
  }
}

返回：

  • 最相关的文档片段，匹配您的查询
  • 来源信息（存储库、文件路径）
  • 每个结果的相似度得分

架构

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

  • 核心组件：

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

  • 关键库：

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

测试

单元测试

运行测试套件：

npm test

手动测试

对于手动测试，请遵循以下步骤：

  1. 设置测试项目
mkdir test-project
cd test-project

# 创建自定义的dependencies.json文件（推荐方法）
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > dependencies.json

# 或者，您可以使用标准的依赖文件：

# 对于Node.js项目
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > package.json

# 对于Python项目
echo 'requests==2.26.0
numpy>=1.20.0' > requirements.txt
  1. 使用fastmcp dev测试依赖上下文
# 编译并使CLI可执行
cd /path/to/dependency-context
npx fastmcp dev src/index.ts

# 初始化并索引依赖项（从您的测试项目目录）
tool(InitializeDependencyIndex)

# 在已索引的依赖项中搜索信息
tool(searchDependencyDocs)

故障排除

GitHub API速率限制

如果您遇到“API速率限制超出”的错误：

  1. 在https://github.com/settings/tokens处创建一个GitHub个人访问令牌

  2. 设置为GITHUB_TOKEN环境变量：

    export GITHUB_TOKEN=your_token_here

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

    # 可选但推荐以获得更高的API速率限制
GITHUB_TOKEN=your_token_here

# 显示默认值的可选设置
MIN_CHUNK_SIZE=800
MAX_CHUNK_SIZE=8000
CHUNKS_RETURNED=5

空搜索结果

如果您的搜索返回空结果：

  1. 确保索引过程成功完成
  2. 检查控制台输出是否有任何错误消息
  3. 验证您的搜索查询是否与已索引的依赖项相关
  4. 尝试更一般的查询以查看是否有任何结果返回

权限问题

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

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

开发

# 克隆仓库
git clone https://github.com/yourusername/dependency-context.git

# 安装依赖项
cd dependency-context
npm install

# 使用fastmcp dev本地运行MCP服务器
npx fastmcp dev src/index.ts

# 测试CLI下载命令
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已经作为推荐方法支持）
  • 增量索引：避免重新处理未更改的存储库
  • 可配置分块：文档拆分的自定义策略
  • 替代模型：支持不同的嵌入模型
  • 缓存层：提高频繁访问文档的性能

许可

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

✅ 允许：

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

❌ 不允许：

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

详情请参阅LICENSE文件中的完整许可文本和许可细节。

版权所有 © 2024 DarianB