RegistryTools

БесплатноНе проверен

A standalone MCP Tool Registry server providing generic tool search and discovery for MCP clients, reducing token consumption and improving tool selection accur

автор: GeerMrc

GitHub Embed

Описание

A standalone MCP Tool Registry server providing generic tool search and discovery for MCP clients, reducing token consumption and improving tool selection accuracy.

README

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

Python Version License MCP

简介

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>

详细文档请参考:

使用示例

# 搜索工具
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 管理界面

许可证

MIT License - 详见 LICENSE 文件

致谢

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

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

from github.com/GeerMrc/RegistryTools

Установка RegistryTools

У этого сервера нет опубликованного пакета — он собирается из исходников. Открой репозиторий и следуй инструкции в README.

▸ github.com/GeerMrc/RegistryTools

FAQ

RegistryTools MCP бесплатный?

Да, RegistryTools MCP бесплатный — установка в пару кликов через Unyly без оплаты.

Нужен ли API-ключ для RegistryTools?

Нет, RegistryTools работает без API-ключей и переменных окружения.

RegistryTools — hosted или self-hosted?

Self-hosted: сервер запускается локально на твоей машине командой из раздела установки.

Как установить RegistryTools в Claude Desktop, Claude Code или Cursor?

Открой RegistryTools на unyly.org, выбери вкладку своего клиента (Claude Desktop, Claude Code, Cursor) и нажми Install — конфиг сгенерируется автоматически, без правки JSON.

Compare RegistryTools with

RegistryToolsvsGitHub RegistryToolsvsFilesystem RegistryToolsvsMemory RegistryToolsvsTemplate MCP Server

Не уверен что выбрать?

Найди свой стек за 60 секунд

Автор?

Embed-бейдж для README

Похожее

Все в категории development

Command Palette

RegistryTools

Описание

README

简介

核心价值

快速开始

安装

传输协议

STDIO 模式 (默认)

Streamable HTTP 模式 (远程部署)

存储后端选择

fastmcp.json 配置

Claude Code (VSCode) 配置

方式 1：CLI 命令（推荐）

方式 2：配置文件

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

快速配置（单行）

STDIO 模式完整配置

HTTP 模式完整配置

参数分类说明

配置范围

配置选项

完整配置参数表格

完整配置示例

Embedding 搜索配置（可选）

高级功能

API Key 认证

使用示例

功能特性

搜索算法

MCP 工具接口

MCP 资源接口

架构设计

开发

环境设置

运行测试

代码格式化

贡献指南

文档

性能指标

路线图

v0.2.1 (当前 - 2026-01-11)

v0.3.0 (计划中)

相关文档

用户文档

技术文档

开发文档

项目管理

许可证

致谢

Установка RegistryTools

FAQ

RegistryTools MCP бесплатный?

Нужен ли API-ключ для RegistryTools?

RegistryTools — hosted или self-hosted?

Как установить RegistryTools в Claude Desktop, Claude Code или Cursor?

Похожие MCP

GitHub

Filesystem

Memory

Template MCP Server

Compare RegistryTools with