RegistryTools

版本: v0.2.1 更新日期: 2026-01-11 独立 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 安装（推荐）
pip install registry-tools

# 或使用 uvx 无需安装
uvx registry-tools

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

注意:

• 生产环境: 使用 pip install registry-tools 或 uvx registry-tools
• 本地开发: 使用 pip install -e . 安装后，直接使用 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"]
    }
  }
}

生产环境配置 (推荐用于生产):

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

存储后端选择

RegistryTools 支持两种存储后端用于持久化工具元数据：

存储类型	适用场景	配置方式
JSON	小规模工具集（< 1000 工具），默认	registry-tools
SQLite	大规模工具集（> 1000 工具），高性能	export REGISTRYTOOLS_STORAGE_BACKEND=sqlite

默认行为：使用 JSON 文件存储，适合大多数场景。

何时使用 SQLite：

• 工具数量超过 1000 个
• 需要高性能查询和过滤
• 需要支持并发访问
• 需要 ACID 事务保证

环境变量配置：

# 使用 SQLite 存储
export REGISTRYTOOLS_STORAGE_BACKEND=sqlite
registry-tools

# 或使用 CLI 参数
registry-tools --storage-backend sqlite

完整配置示例：

{
  "mcpServers": {
    "RegistryTools": {
      "command": "registry-tools",
      "env": {
        "REGISTRYTOOLS_STORAGE_BACKEND": "sqlite"
      }
    }
  }
}

性能对比：

操作	JSON 存储	SQLite 存储
加载 1000 工具	~75ms	~18ms (76% 提升)
按标签过滤	~15ms	~4ms (73% 提升)
内存占用	~15MB	~6MB (60% 减少)

详见 存储选择指南。

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

生产环境配置 (推荐用于生产):

# 基础配置（使用 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"
      }
    }
  }
}

生产环境配置 (推荐用于生产):

{
  "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":"uvx","args":["registry-tools"]}' --scope user

HTTP 模式：

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

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_TRANSPORT": "stdio",
    "REGISTRYTOOLS_LOG_LEVEL": "INFO",
    "REGISTRYTOOLS_ENABLE_AUTH": "false",
    "REGISTRYTOOLS_SEARCH_METHOD": "bm25",
    "REGISTRYTOOLS_STORAGE_BACKEND": "json",
    "REGISTRYTOOLS_DEVICE": "cpu",
    "REGISTRYTOOLS_DESCRIPTION": "统一的 MCP 工具注册与搜索服务"
  }
}' --scope user

生产环境配置 (推荐用于生产):

# 基础配置（使用 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_TRANSPORT": "stdio",
    "REGISTRYTOOLS_LOG_LEVEL": "INFO",
    "REGISTRYTOOLS_ENABLE_AUTH": "false",
    "REGISTRYTOOLS_SEARCH_METHOD": "bm25",
    "REGISTRYTOOLS_STORAGE_BACKEND": "json",
    "REGISTRYTOOLS_DEVICE": "cpu",
    "REGISTRYTOOLS_DESCRIPTION": "统一的 MCP 工具注册与搜索服务"
  }
}' --scope user

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

参数分类说明

参数	STDIO	HTTP	说明
REGISTRYTOOLS_DATA_PATH	✓	✓	数据存储目录
REGISTRYTOOLS_TRANSPORT	✓	-	传输协议
REGISTRYTOOLS_LOG_LEVEL	✓	✓	日志级别
REGISTRYTOOLS_ENABLE_AUTH	✓	✓	API Key 认证
REGISTRYTOOLS_STORAGE_BACKEND	✓	✓	存储后端
REGISTRYTOOLS_SEARCH_METHOD	✓	✓	搜索方法
REGISTRYTOOLS_DEVICE	✓	✓	Embedding 设备
REGISTRYTOOLS_DESCRIPTION	✓	✓	服务器描述

配置范围

# 项目级配置（可版本控制）
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	stdio, http
REGISTRYTOOLS_LOG_LEVEL	日志级别	INFO	DEBUG, INFO, WARNING, ERROR
REGISTRYTOOLS_ENABLE_AUTH	启用 API Key 认证	false	true, false, 1, 0, yes, no
REGISTRYTOOLS_SEARCH_METHOD	默认搜索方法	bm25	regex, bm25, embedding
REGISTRYTOOLS_STORAGE_BACKEND	存储后端类型	json	json, sqlite
REGISTRYTOOLS_DEVICE	Embedding 模型计算设备	cpu	cpu, gpu:0, gpu:1, auto
REGISTRYTOOLS_DESCRIPTION	MCP 服务器描述	统一的 MCP 工具注册与搜索服务...	任意有效字符串

完整配置示例

Claude Desktop 完整配置 (JSON 格式):

{
  "mcpServers": {
    "RegistryTools": {
      "command": "uvx",
      "args": ["registry-tools"],
      "env": {
        "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools",
        "REGISTRYTOOLS_TRANSPORT": "stdio",
        "REGISTRYTOOLS_LOG_LEVEL": "INFO",
        "REGISTRYTOOLS_ENABLE_AUTH": "false",
        "REGISTRYTOOLS_SEARCH_METHOD": "bm25",
        "REGISTRYTOOLS_STORAGE_BACKEND": "json",
        "REGISTRYTOOLS_DEVICE": "cpu",
        "REGISTRYTOOLS_DESCRIPTION": "统一的 MCP 工具注册与搜索服务"
      }
    }
  }
}

Claude Code add-json 配置: 参见上方 方式 3：JSON 配置命令 章节的完整配置示例。

快速示例:

# 自定义数据路径
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

# Embedding 搜索 + GPU
export REGISTRYTOOLS_SEARCH_METHOD=embedding
export REGISTRYTOOLS_DEVICE=gpu:0
registry-tools

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

详细配置: 参见 配置指南

Embedding 搜索配置（可选）

Embedding 搜索提供语义理解能力，但需要额外的依赖和资源。

安装依赖:

pip install registry-tools[embedding]

环境变量:

• REGISTRYTOOLS_SEARCH_METHOD=embedding - 启用语义搜索
• REGISTRYTOOLS_DEVICE=gpu:0 - 使用 GPU 加速（可选）
  • cpu - 使用 CPU（默认）
  • gpu:0 / gpu:1 - 使用指定 GPU
  • auto - 自动选择 GPU 或 CPU

性能对比:

方法	速度	准确率	内存占用
regex	最快	高	~50MB
bm25	快	高	~50MB
embedding	慢	最高	~550MB

GPU 内存需求:

模型	GPU 内存	CPU 内存
paraphrase-multilingual-MiniLM-L12-v2 (默认)	~500MB	~1GB
all-MiniLM-L6-v2	~100MB	~300MB

---

高级功能

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 工具（支持 regex/bm25/embedding）
• search_hot_tools - 快速搜索热工具（性能优化，仅搜索高频工具）
• get_tool_definition - 获取工具的完整定义
• list_tools_by_category - 按类别列出工具
• register_tool - 动态注册新工具

性能提示: 对于大型工具集，使用 search_hot_tools 可提升搜索速度 40-60%。

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.2.1 (当前 - 2026-01-11)

• ✅ 所有 v0.1.1 功能
• ✅ 搜索引擎全局配置（REGISTRYTOOLS_SEARCH_METHOD 环境变量）
• ✅ search_method 参数可选（默认使用环境变量）
• ✅ search_hot_tools 自动回退机制（不支持 embedding 时自动使用 bm25）

v0.3.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