mcp-pkg本地

![CI](https://github.com/descoped/mcp-pkg-local/actions/workflows/ci.yml) ![MIT License](LICENSE) ![MCP Tool](https://modelcontextprotocol.io) ](https://nodejs.org) ![TypeScript](https://www.typescriptlang.org) ](https://www.npmjs.com/package/@descoped/mcp-pkg-local) ![Test Coverage](https://github.com/descoped/mcp-pkg-local/actions)

一个MCP（模型上下文协议）服务器，使LLM能够读取和理解本地安装的包源代码，通过提供对实际安装的包的直接访问，帮助减少API幻觉。

特性

核心能力

🔍 自动检测：自动检测Python或Node.js项目
📖 源代码访问：直接读取实际安装的包源代码
⚡ 高性能：SQLite缓存的有效性检查速度提高了40倍
🎯 零配置：立即使用标准项目结构
🚀 生产就绪：300多项测试，14个CI阶段，全面的错误处理

高级过滤

📊 摘要模式：获得包裹数量，减少99%的代币
🔎 正则表达式过滤：按模式匹配筛选包
📦 类别筛选：独立的生产/开发依赖关系（Node.js）
🏷️ 分组过滤：预定义的组（测试、布线、建筑等）
🎚️ 智能限制：默认50个包以优化LLM令牌使用
🚫 类型排除：可选择排除@types包

语言支持

📦 Node.js：完全支持依赖关系分类

- 包管理器：npm、pnpm、yarn、bun - 生产与开发分类 - 范围包（@org/package）

🐍 python：完全支持虚拟环境

- 包管理器：pip、uv（完全支持）、poetry、pipenv（检测） - 虚拟环境：venv、.vev、conda - 用于独立包装操作的瓶子架构 - 注意：依赖关系分类待定

性能优化

💾 SQLite缓存：具有WAL模式的高性能缓存，用于并发访问
📈 相关性评分：优先考虑直接依赖关系（Node.js）
🌲 延迟加载：按需加载文件树
⏱️ 快速操作：~150ms扫描，~10ms读取，~5ms缓存命中
🚀 快40倍：0.03ms与1.2ms的有效性检查（旧JSON缓存）

开发者体验

🛠️ TypeScript 5.9+：严格模式，全类型安全
📦 ES模块：带有导入映射的现代JavaScript
🧪 综合测试：300多个测试，涵盖所有场景
🔒 安全：路径清理、文件大小限制、只读访问
🚀 MCP-SDK：最新的模型上下文协议实现
⚙️ CI/CD：14阶段流水线，总运行时间为4分钟

为什么选择mcp-pkg本地？

LLM经常产生API幻觉或使用训练数据中过时的语法。该工具通过让LLM读取您环境中安装的包的实际源代码来解决这个问题，确保生成的代码与您的确切包版本相匹配。

安装

全局安装（推荐）

npm install -g @descoped/mcp-pkg-local

或者直接与npx一起使用

npx @descoped/mcp-pkg-local

MCP客户端配置

基于CLI的代码助理

克劳德密码（Claude.ai）

创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "pkg-local": {
      "command": "npx",
      "args": ["@descoped/mcp-pkg-local"],
      "env": {
        "DEBUG": "mcp-pkg-local:*"
      }
    }
  }
}

或者使用CLI：

claude mcp add pkg-local -- npx @descoped/mcp-pkg-local

对于内置版本的本地开发/测试：

{
  "mcpServers": {
    "pkg-local": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-pkg-local/dist/index.js"],
      "env": {
        "DEBUG": "mcp-pkg-local:*"
      }
    }
  }
}

Gemini CLI

创建或编辑 ~/.config/gemini/mcp.json:

{
  "mcpServers": {
    "pkg-local": {
      "command": "npx",
      "args": ["@descoped/mcp-pkg-local"]
    }
  }
}

添加后，使用 /mcp list 在Gemini CLI中验证服务器是否已配置。

光标

创建 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "pkg-local": {
      "command": "npx",
      "args": ["-y", "@descoped/mcp-pkg-local"],
      "cwd": "${workspaceFolder}"
    }
  }
}

打开光标设置→ MCP验证连接（绿色状态）。

VS代码扩展

继续扩展

增添 .continue/config.json:

{
  "models": [...],
  "mcpServers": {
    "pkg-local": {
      "command": "npx",
      "args": ["@descoped/mcp-pkg-local"],
      "cwd": "${workspaceFolder}"
    }
  }
}

帆板运动

创建 .windsurf/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "pkg-local": {
      "command": "npx",
      "args": ["-y", "@descoped/mcp-pkg-local"]
    }
  }
}

桌面应用程序

克劳德桌面

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pkg-local": {
      "command": "npx",
      "args": ["-y", "@descoped/mcp-pkg-local"]
    }
  }
}

添加后，完全重新启动Claude Desktop。您将看到MCP指示器(🔌) 在对话输入框中。

用法

配置后，MCP服务器提供两个主要工具：

包裹扫描工具

工具：扫描包

扫描并索引虚拟环境中的所有包。

参数：

forceRefresh （bool）-即使索引存在，也强制重新扫描
filter （string）-用于过滤包名称的正则表达式模式（例如。， ^@types/, eslint)
limit （number）-要返回的最大包数（默认值：50）
summary （bool）-仅返回摘要计数
category （string）-按生产/开发/全部筛选
includeTypes （bool）-包括@types包
group （string）-按组筛选（测试、建筑、植绒等）

示例：

// Scan with default settings (returns 50 packages)
scan-packages

// Force refresh the cache
scan-packages --forceRefresh

// Get summary only (token-efficient)
scan-packages --summary
// Returns: { total: 304, languages: { javascript: 304 }, categories: { production: 12, development: 292 } }

// Filter by regex pattern
scan-packages --filter "^react"  // All React packages
scan-packages --filter "eslint"  // Packages containing 'eslint'

// Filter by category
scan-packages --category production  // Production dependencies only
scan-packages --category development // Dev dependencies only

// Filter by predefined groups
scan-packages --group testing   // Testing tools (jest, mocha, vitest, etc.)
scan-packages --group building  // Build tools (webpack, vite, rollup, etc.)
scan-packages --group linting   // Linters (eslint, prettier, etc.)
scan-packages --group typescript // TypeScript-related packages

// Exclude @types packages
scan-packages --includeTypes false

// Limit results
scan-packages --limit 10  // Return only 10 packages

工具：读取包

从特定包中读取源文件。

参数：

packageName （字符串，必填）-要读取的包名称
filePath （string）-包中的特定文件
includeTree （bool）-包含完整的文件树（默认值：false）
maxDepth （number）-树遍历的最大深度（默认值：2）
pattern （string）-用于过滤文件的Glob模式（例如。， *.ts, src/**)

示例：

// Get main files only (default - very efficient)
read-package express
// Returns: mainFiles, fileCount, package.json content

// Read specific file
read-package express lib/router/index.js

// Get full file tree
read-package express --includeTree

// Limit tree depth
read-package express --includeTree --maxDepth 2

// Filter files by pattern
read-package typescript --includeTree --pattern "*.d.ts"
read-package express --includeTree --pattern "lib/**"

性能特征（v0.2.0）

该工具已针对LLM令牌消费进行了优化：

令牌使用情况比较

操作	v0.1.0	v0.2.0	减少
全扫描（所有包）	20000	2000	90%
摘要扫描	N/A	200	99%
筛选扫描（例如测试工具）	20000	500	97.5%
读取包（默认）	5000	300	94%
用树读取包	5000	1000	80%
大型TypeScript文件（AST）	10000	300	99.7%

关键优化

默认限制：默认情况下只返回50个包，而不是全部
懒惰文件树：除非请求完整的树，否则仅显示主文件
相对路径：使用相对路径在路径字符串上节省约30%
智能过滤：多种方法可以准确地得到你需要的东西
摘要模式：获取不包含包裹详细信息的计数
AST提取：TypeScript/JavaScript文件解析为99.7%的较小输出
简化的API：两个工具总共只有3个参数（v0.2.0）

运作原理

环境检测：自动检测Python(.venv/venv)或Node.js(package.json)项目
包发现:

- Python：扫描 site-packages 并阅读 .dist-info 元数据 - Node.js：扫描 node_modules 包括范围包

智能缓存：SQLite数据库(.pkg-local-cache/cache.db)用于高性能查找
源代码阅读：为LLM提供文件树和实际源代码

瓶子建筑

该项目包括一个用于隔离包管理操作的“瓶子”架构：

壳牌RPC发动机（BRPC-001）

用于有状态命令执行的持久shell进程管理
基于活动的超时系统，在stdout进度时重置
跨平台支持（Windows PowerShell、Linux bash、macOS bash）
命令队列，超时时自动清理
虚拟环境激活支持

音量控制器（BVOL-001）

12个以上包管理器（npm、pip、poetry、maven等）的缓存管理
跨平台缓存路径检测和挂载
通过缓存持久性将CI/CD性能提高10倍
环境变量注入，实现一致的包操作
使用可操作的错误消息进行正确的错误处理

包管理器适配器

pip和uv（Python包管理器）的统一接口
动态工具检测取代了硬编码路径
具有基于活动的重置行为的可配置超时
支持requirements.txt、pyproject.toml和锁定文件
清洁、隔离的环境，防止系统污染

发展

先决条件

Node.js 20+（建议使用LTS）
npm 10+或pnpm
Python 3.9+虚拟环境（用于Python支持）
带Node_modules的Node.js项目（用于Node.js支持）

设置

# Clone the repository
git clone https://github.com/descoped/mcp-pkg-local.git
cd mcp-pkg-local

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Development mode
npm run dev

# Clean build artifacts and cache
npm run clean        # Remove everything (dist, node_modules, cache)
npm run clean:cache  # Remove only cache files

项目结构

mcp-pkg-local/
├── src/
│   ├── index.ts          # Entry point
│   ├── server.ts         # MCP server setup
│   ├── tools/            # MCP tool implementations
│   ├── scanners/         # Language-specific scanners
│   └── utils/            # Utilities
├── tests/                # Test suite
└── dist/                 # Compiled output

测试

该项目包括使用具有可配置超时的Vitest进行全面测试：

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:ui

测试超时配置

测试使用集中的超时预设，这些预设会自动根据CI环境进行调整：

短期测试 （5s）：单元测试、快速验证
中等测试 （15秒）：集成测试、包操作
长时间测试 （30秒）：端到端工作流程，复杂场景

在CI环境中，超时会自动乘以1.5倍以提高可靠性。

测试按顺序运行，以避免SQLite锁定问题和竞争条件。

配置

环境变量

以下环境变量可用于自定义行为：

缓存和存储

BOTTLE_CACHE_ROOT -所有包数据的自定义缓存目录（默认： .pkg-local-cache)

- 例子： export BOTTLE_CACHE_ROOT=/tmp/pkg-cache - 用于：包缓存、SQLite数据库、瓶子体积

测试

TEST_BASE_DIR -测试临时文件的基本目录（默认： output/test-temp)
PRESERVE_TEST_DIRS_ON_FAILURE -在调试失败时保留测试目录（默认值： true 当地， false 在CI）
USE_SYSTEM_TEMP -使用系统临时目录而不是本地目录（默认： false 当地， true 在CI）

调试

DEBUG=mcp-pkg-local:* -启用调试日志记录
NODE_ENV=production -生产模式（禁用调试功能）

超时配置

PKG_LOCAL_TIMEOUT_MULTIPLIER -所有操作超时的倍数（默认值： 1.0)

- 例子： export PKG_LOCAL_TIMEOUT_MULTIPLIER=2 （将所有超时加倍） - 适用于：慢速网络、CI环境或调试

系统使用基于活动的超时，在stdout进度时重置：

快速操作 （5s）：版本检查、包列表
标准操作 （30秒）：软件包安装、虚拟环境创建
扩展操作 （60年代）：大型装置（很少使用）

当命令显示进度输出（下载、安装）时，超时会自动重置。错误输出（stderr）不会重置超时，以防止挂起失败的命令。

缓存管理

缓存系统使用SQLite实现最佳性能：

地点： ${BOTTLE_CACHE_ROOT}/cache.db （或 .pkg-local-cache/cache.db 如果未设置）
模式：WAL（预写日志）用于并发访问
TTL:1小时默认有效期
刷新：使用 --forceRefresh 强制重新扫描

自定义缓存位置

您可以使用自定义缓存位置 BOTTLE_CACHE_ROOT 环境变量：

# Absolute path
export BOTTLE_CACHE_ROOT=/tmp/pkg-cache

# Relative path (relative to project root)
export BOTTLE_CACHE_ROOT=build/cache

# In CI/CD environments
export BOTTLE_CACHE_ROOT=${CI_PROJECT_DIR}/.pkg-cache

这对于以下情况特别有用：

需要在构建之间进行持久缓存的CI/CD环境
共享开发环境
带有已挂载缓存卷的Docker容器
使用隔离缓存目录进行测试

支持的环境

python

✅ 虚拟环境（venv、.vev）
✅ 包管理器：pip、poetry、uv、pipenv（基本检测）
✅ 标准pip包
✅ 可编辑安装（-e）
✅ 命名空间包
⚠️ 限制：尚未进行依赖关系分类
🚧 康达环境（规划）

Node.js/JavaScript

✅ node_modules目录
✅ 包管理器：npm、pnpm、yarn、bun（完全支持）
✅ 范围包（@org/package）
✅ TypeScript包
✅ ESM和CommonJS模块
✅ 生产与发展分类

局限性

Python依赖分类尚未实现
仅限本地环境（无系统包）
只读访问（不能修改包）
源文件的文件大小限制为10MB
Go、Rust、Java支持计划在未来版本中推出

安全

从不读取虚拟环境或node_modules之外的文件
路径清理可防止目录遍历
不执行代码，只读取
二进制文件被阻止

贡献

欢迎投稿！请阅读我们的贡献指南了解详情。

开发工作流程

分叉存储库
创建要素分支
为新功能编写测试
确保所有测试通过
提交拉取请求

路线图

v0.1.x（已发布）

\[x\] Python虚拟环境支持
\[x\] 基本包裹扫描和读取
\[x\] MCP服务器实现
\[x\] 缓存系统
\[x\] 性能优化（令牌减少90%）
\[x\] 高级过滤（正则表达式、类别、组）
\[x\] 延迟文件树加载
\[x\] 最小令牌的摘要模式
\[x\] Node.js/JavaScript支持
\[x\] 多包管理器支持

v0.2.0（当前）

\[x\] 用于独立包装操作的瓶子架构
\[x\] 具有基于活动的超时的Shell RPC引擎
\[x\] 用于缓存管理的卷控制器
\[x\] 动态刀具检测（无硬编码路径）
\[x\] TypeScript/JavaScript的AST提取（减少99.7%）
\[x\] 简化的API（参数减少77%）
\[x\] 300+测试，14个CI阶段
\[x\] 生产就绪错误处理

未来版本

\[\]Python依赖分类（关键）

\[\]智能包装优先级

\[\]康达环境支持

\[\]包别名解析

\[\]依赖树可视化

\[\]Go模块支持

\[\]防锈/货运支持

\[\]导入检测时自动触发

\[\]包文档提取

许可证

MIT许可证-请参阅许可证详细信息文件

致谢

内置：

支持

文档

______________________________________________________________________

由以下材料制成❤️ 为了更好地生成LLM代码

MCP Pkg Local

快速接入

详细介绍