registry-tools 0.2.0

A universal MCP Tool Registry Server with search capabilities

RegistryTools

版本: v0.1.1 更新日期: 2026-01-09 独立 MCP Tool Registry Server - 通用工具搜索与发现服务

---

简介

RegistryTools 是一个独立的 MCP Tool Registry Server，提供通用的工具搜索和发现能力。它可以被任何支持 MCP 协议的客户端（如 DeepThinking Agent、Cursor IDE、Claude Desktop）使用。

核心价值

• 减少 Token 消耗 85%: 从 ~77K 降至 ~8.7K（按需加载工具）
• 提升准确率: 工具选择准确率从 49% 提升至 74%
• 解耦复用: 独立部署，任何 MCP 客户端都可连接

---

⚠️ PyPI 发布状态

RegistryTools 目前尚未发布到 PyPI，仅支持从源码本地安装。

安装方式	命令	配置命令
本地安装（当前）	pip install -e . 或 uv pip install -e .	registry-tools ✅
PyPI 安装（不可用）	pip install registry-tools	-
uvx 运行（不可用）	uvx registry-tools	- ❌

MCP 配置示例（本地安装后）:

{
  "command": "registry-tools",
  "env": { "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools" }
}

---

快速开始

安装

# 本地开发环境（从源码安装）
cd RegistryTools
pip install -e .

# 或从 PyPI 安装（发布后）
pip install registry-tools

# 使用 uvx（仅 PyPI 发布后可用）
uvx registry-tools

注意:

• 本地开发环境: 使用 pip install -e . 安装后，直接使用 registry-tools 命令
• PyPI 发布后: 可以使用 uvx registry-tools 无需安装

传输协议

RegistryTools 支持多种 MCP 传输协议:

协议	适用场景	配置方式
STDIO	本地 CLI 集成 (默认)	registry-tools
Streamable HTTP	远程服务部署	registry-tools --transport http

STDIO 模式 (默认)

适用于 Claude Desktop、本地脚本等本地集成场景。

Claude Desktop 配置:

在 Claude Desktop 配置文件中添加:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

本地开发环境配置 (推荐用于开发):

{
  "mcpServers": {
    "RegistryTools": {
      "command": "registry-tools",
      "args": ["--data-path", "~/.RegistryTools"]
    }
  }
}

PyPI 发布后配置 (推荐用于生产):

{
  "mcpServers": {
    "RegistryTools": {
      "command": "uvx",
      "args": ["registry-tools", "--data-path", "~/.RegistryTools"]
    }
  }
}

Streamable HTTP 模式 (远程部署)

适用于远程服务、容器化部署、多客户端共享等场景。

启动 HTTP 服务器:

# 使用默认参数 (127.0.0.1:8000)
registry-tools --transport http

# 自定义主机和端口
registry-tools --transport http --host 0.0.0.0 --port 8000

# 自定义路径
registry-tools --transport http --port 8000 --path /api/mcp

客户端连接示例:

{
  "mcpServers": {
    "RegistryTools": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

fastmcp.json 配置

使用 fastmcp.json 进行声明式配置 (推荐):

# 使用配置文件启动
fastmcp run fastmcp.json

# 或直接运行 (自动检测当前目录的 fastmcp.json)
fastmcp run

fastmcp.json 示例:

{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "src/registrytools/__main__.py",
    "entrypoint": "main"
  },
  "deployment": {
    "transport": "http",
    "host": "0.0.0.0",
    "port": 8000,
    "path": "/mcp"
  }
}

详见: fastmcp.json (STDIO 默认配置) 详见: fastmcp.http.json (HTTP 配置示例)

Claude Code (VSCode) 配置

Claude Code 是 Anthropic 官方的 VSCode AI 助手，支持通过 MCP 协议集成 RegistryTools。

方式 1：CLI 命令（推荐）

使用 Claude Code CLI 命令快速配置：

STDIO 本地服务器：

本地开发环境配置 (推荐用于开发):

# 基础配置（直接使用已安装的命令）
claude mcp add --transport stdio RegistryTools -- registry-tools

# 带环境变量
claude mcp add --transport stdio RegistryTools \
  --env REGISTRYTOOLS_LOG_LEVEL=INFO \
  -- registry-tools

PyPI 发布后配置 (推荐用于生产):

# 基础配置（使用 uvx）
claude mcp add --transport stdio RegistryTools -- uvx registry-tools

# 带环境变量
claude mcp add --transport stdio RegistryTools \
  --env REGISTRYTOOLS_LOG_LEVEL=INFO \
  -- uvx registry-tools

Streamable HTTP 远程服务器：

# 无认证
claude mcp add --transport http RegistryTools-Remote http://localhost:8000/mcp

# 使用 API Key 认证
# 1. 先启用认证并创建 API Key
registry-tools --transport http --enable-auth
registry-tools api-key create "Claude Code" --permission read

# 2. 添加服务器（使用 API Key）
claude mcp add --transport http RegistryTools-Remote \
  http://localhost:8000/mcp \
  --header "X-API-Key: rtk_your_api_key_here"

管理命令：

claude mcp list              # 列出所有服务器
claude mcp get RegistryTools  # 查看详情
claude mcp remove RegistryTools  # 删除服务器

配置范围：

# 项目级配置（可版本控制）
# 本地开发环境
claude mcp add --scope project --transport stdio RegistryTools -- registry-tools
# PyPI 发布后
claude mcp add --scope project --transport stdio RegistryTools -- uvx registry-tools

# 用户级配置（跨项目使用）
# 本地开发环境
claude mcp add --scope user --transport stdio RegistryTools -- registry-tools
# PyPI 发布后
claude mcp add --scope user --transport stdio RegistryTools -- uvx registry-tools

方式 2：配置文件

创建 .claude/config.json（项目级）或 ~/.claude/config.json（用户级）：

本地开发环境配置 (推荐用于开发):

{
  "mcpServers": {
    "RegistryTools": {
      "command": "registry-tools",
      "env": {
        "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools",
        "REGISTRYTOOLS_LOG_LEVEL": "INFO"
      }
    }
  }
}

PyPI 发布后配置 (推荐用于生产):

{
  "mcpServers": {
    "RegistryTools": {
      "command": "uvx",
      "args": ["registry-tools"],
      "env": {
        "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools",
        "REGISTRYTOOLS_LOG_LEVEL": "INFO"
      }
    }
  }
}

方式 3：JSON 配置命令 (add-json)

使用 claude mcp add-json 命令直接通过 JSON 配置添加 MCP 服务器：

STDIO 本地服务器：

本地开发环境配置 (推荐用于开发):

# 基础配置
claude mcp add-json "RegistryTools" '{"command": "registry-tools"}' --scope user

# 带环境变量
claude mcp add-json "RegistryTools" '{
  "command": "registry-tools",
  "env": {
    "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools",
    "REGISTRYTOOLS_LOG_LEVEL": "INFO"
  }
}' --scope user

PyPI 发布后配置 (推荐用于生产):

# 基础配置（使用 uvx）
claude mcp add-json "RegistryTools" '{"command": "uvx", "args": ["registry-tools"]}' --scope user

# 带环境变量
claude mcp add-json "RegistryTools" '{
  "command": "uvx",
  "args": ["registry-tools"],
  "env": {
    "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools",
    "REGISTRYTOOLS_LOG_LEVEL": "INFO"
  }
}' --scope user

Streamable HTTP 远程服务器：

# 无认证
claude mcp add-json "RegistryTools-Remote" '{
  "url": "http://localhost:8000/mcp"
}' --scope user

# 使用 API Key 认证
claude mcp add-json "RegistryTools-Remote" '{
  "url": "http://localhost:8000/mcp",
  "headers": {
    "X-API-Key": "rtk_your_api_key_here"
  }
}' --scope user

配置范围：

# 项目级配置（可版本控制）
claude mcp add-json "RegistryTools" '{...}' --scope project

# 用户级配置（跨项目使用，默认）
claude mcp add-json "RegistryTools" '{...}' --scope user

# 本地级配置（项目特定，gitignored）
claude mcp add-json "RegistryTools" '{...}' --scope local

配置选项

RegistryTools 支持灵活的配置方式。完整配置说明请参见 配置指南。

常用环境变量:

• REGISTRYTOOLS_DATA_PATH - 数据目录路径（默认: ~/.RegistryTools）
• REGISTRYTOOLS_TRANSPORT - 传输协议（默认: stdio）
• REGISTRYTOOLS_LOG_LEVEL - 日志级别（默认: INFO）
• REGISTRYTOOLS_ENABLE_AUTH - 启用 API Key 认证（默认: false）
• REGISTRYTOOLS_DESCRIPTION - MCP 服务器描述（可选，默认: 统一的 MCP 工具注册与搜索服务，用于发现和筛选可用工具，提升任务执行工具调用准确性，复杂任务工具调用效率）

快速示例:

# 自定义数据路径
export REGISTRYTOOLS_DATA_PATH=/custom/path
registry-tools

# HTTP 模式 + 认证
export REGISTRYTOOLS_TRANSPORT=http
export REGISTRYTOOLS_ENABLE_AUTH=true
registry-tools --host 0.0.0.0 --port 8000

配置优先级: 环境变量 > CLI 参数 > 默认值

详细配置: 参见 配置指南

---

高级功能

API Key 认证

# 创建 API Key
registry-tools api-key create "My Key" --permission read

# 列出 API Key
registry-tools api-key list

# 删除 API Key
registry-tools api-key delete <key-id>

详细文档请参考:

• API 文档
• 用户指南

使用示例

# 搜索工具
search_tools("github create pull request", "bm25", 5)

# 获取工具定义
get_tool_definition("github.create_pull_request")

# 按类别列出工具
list_tools_by_category("github", 20)

# 动态注册工具
register_tool(
    name="my.custom.tool",
    description="A custom tool for specific purpose"
)

---

功能特性

搜索算法

算法	描述	速度	适用场景
Regex	正则表达式精确匹配	最快	精确名称匹配
BM25	BM25 关键词搜索（支持中文分词）	快	关键词搜索（推荐）
Embedding	语义搜索（支持中英文）	中	语义理解和模糊匹配（可选依赖）

MCP 工具接口

• search_tools - 搜索可用的 MCP 工具
• get_tool_definition - 获取工具的完整定义
• list_tools_by_category - 按类别列出工具
• register_tool - 动态注册新工具

MCP 资源接口

• registry://stats - 工具注册表统计信息
• registry://categories - 所有工具类别

---

架构设计

MCP Clients (任何支持 MCP 的应用)
    │
    ▼
RegistryTools (独立 MCP Server)
    │
    ├── Tool Registry (工具注册表)
    │   └── 管理所有工具的元数据和索引
    │
    ├── Search Engine (搜索引擎)
    │   ├── Regex 搜索 (精确匹配)
    │   ├── BM25 搜索 (关键词)
    │   └── Embedding 搜索 (语义)
    │
    └── Storage Layer (存储层)
        ├── JSON 文件存储
        └── SQLite 存储

详见 ARCHITECTURE.md

---

开发

环境设置

# 克隆项目
git clone https://github.com/maric/RegistryTools.git
cd RegistryTools

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 安装开发依赖
pip install -e ".[dev]"

运行测试

# 运行所有测试
pytest

# 查看覆盖率
pytest --cov=RegistryTools --cov-report=html

代码格式化

# 格式化代码
black src/registrytools/ tests/

# 代码检查
ruff check src/registrytools/ tests/

贡献指南

请参阅 CONTRIBUTING.md

---

文档

• 架构设计 - 系统架构说明
• API 文档 - API 接口文档
• 使用示例 - 代码示例
• 开发流程规范 - 开发流程规范
• 任务追踪 - 项目任务追踪
• 变更日志 - 版本变更记录

---

性能指标

指标	目标值
搜索响应时间	< 200ms (1000+ 工具)
内存占用	< 100MB (1000+ 工具)
索引构建时间	< 2s (1000+ 工具)

---

路线图

v0.1.1 (当前 - 2026-01-09)

• ✅ 基础工具注册和搜索
• ✅ Regex 搜索算法（精确匹配）
• ✅ BM25 搜索算法（支持中文分词）
• ✅ Embedding 语义搜索（可选依赖，支持中英文）
• ✅ JSON/SQLite 存储
• ✅ MCP 工具和资源接口
• ✅ STDIO 和 Streamable HTTP 传输协议支持
• ✅ fastmcp.json 配置文件支持
• ✅ 测试覆盖率 87%
• ✅ 完整文档和使用示例
• ✅ 性能优化（索引缓存、冷热工具分离）

v0.2.0 (计划中)

• ⏳ 分布式工具注册
• ⏳ 工具依赖管理
• ⏳ Web UI 管理界面

---

相关文档

用户文档

• INSTALLATION.md - 安装指南
• USER_GUIDE.md - 用户使用指南
• CONFIGURATION.md - 配置参数说明
• TROUBLESHOOTING.md - 故障排除
• BEST_PRACTICES.md - 最佳实践

技术文档

• API.md - API 参考文档
• ARCHITECTURE.md - 架构设计
• CLAUDE_CONFIG.md - Claude 配置指南
• IDE_CONFIG.md - IDE 配置指南

开发文档

• CONTRIBUTING.md - 贡献指南
• PUBLISHING.md - PyPI 发布指南
• DEVELOPMENT_WORKFLOW.md - 开发流程规范
• SCRIPTS_GUIDE.md - 脚本工具指南

项目管理

• TASK.md - 项目任务追踪
• CHANGELOG.md - 变更日志

---

许可证

MIT License - 详见 LICENSE 文件

---

致谢

• Anthropic - MCP 协议设计
• FastMCP - MCP 服务器框架
• rank-bm25 - BM25 算法实现

---

项目维护者: Maric 项目主页: GitHub