registry-tools 0.2.1
A universal MCP Tool Registry Server with search capabilities
License: MIT
Requires Python: >=3.10
Keywords: anthropic, claude, mcp, model-context-protocol, tool-registry, tool-search

# RegistryTools

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

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Protocol-orange.svg)](https://modelcontextprotocol.io/)

---

## 简介

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

### 核心价值

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

---

---

## 快速开始

### 安装

```bash
# 从 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`

**本地开发配置** (用于开发):
```json
{
  "mcpServers": {
    "RegistryTools": {
      "command": "registry-tools",
      "args": ["--data-path", "~/.RegistryTools"]
    }
  }
}
```

**生产环境配置** (推荐用于生产):
```json
{
  "mcpServers": {
    "RegistryTools": {
      "command": "uvx",
      "args": ["registry-tools", "--data-path", "~/.RegistryTools"]
    }
  }
}
```

#### Streamable HTTP 模式 (远程部署)

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

**启动 HTTP 服务器**:

```bash
# 使用默认参数 (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
```

**客户端连接示例**:

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

### 存储后端选择

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

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

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

**何时使用 SQLite**：
- 工具数量超过 1000 个
- 需要高性能查询和过滤
- 需要支持并发访问
- 需要 ACID 事务保证

**环境变量配置**：

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

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

**完整配置示例**：

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

**性能对比**：

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

详见 [存储选择指南](docs/STORAGE.md)。

### fastmcp.json 配置

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

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

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

**fastmcp.json 示例**:

```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](fastmcp.json) (STDIO 默认配置)
详见: [fastmcp.http.json](fastmcp.http.json) (HTTP 配置示例)

### Claude Code (VSCode) 配置

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

#### 方式 1：CLI 命令（推荐）

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

**STDIO 本地服务器**：

**本地开发配置** (用于开发):
```bash
# 基础配置（直接使用已安装的命令）
claude mcp add --transport stdio RegistryTools -- registry-tools

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

**生产环境配置** (推荐用于生产):
```bash
# 基础配置（使用 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 远程服务器**：
```bash
# 无认证
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"
```

**管理命令**：
```bash
claude mcp list              # 列出所有服务器
claude mcp get RegistryTools  # 查看详情
claude mcp remove RegistryTools  # 删除服务器
```

**配置范围**：
```bash
# 项目级配置（可版本控制）
# 本地开发环境
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`（用户级）：

**本地开发配置** (用于开发):
```json
{
  "mcpServers": {
    "RegistryTools": {
      "command": "registry-tools",
      "env": {
        "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools",
        "REGISTRYTOOLS_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

**生产环境配置** (推荐用于生产):
```json
{
  "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 本地服务器**：

**本地开发配置** (用于开发):
```bash
# 基础配置
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
```

**生产环境配置** (推荐用于生产):
```bash
# 基础配置（使用 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 远程服务器**：
```bash
# 无认证
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
```

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

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

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

### 配置选项

RegistryTools 支持灵活的配置方式。完整配置说明请参见 [配置指南](docs/CONFIGURATION.md)。

#### 完整配置参数表格

| 环境变量 | 描述 | 默认值 | 可选值 |
|---------|------|--------|--------|
| `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 格式):
```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 命令):
```bash
claude mcp add-json "RegistryTools" '{
  "command": "uvx",
  "args": ["registry-tools"],
  "env": {
    "REGISTRYTOOLS_DATA_PATH": "$HOME/.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
```

**快速示例**:
```bash
# 自定义数据路径
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 参数 > 默认值

**详细配置**: 参见 [配置指南](docs/CONFIGURATION.md)

### Embedding 搜索配置（可选）

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

**安装依赖**:
```bash
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 认证
```bash
# 创建 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 文档](docs/API.md#api-key-认证-phase-15)
- [用户指南](docs/USER_GUIDE.md#api-key-认证-phase-15)

### 使用示例

```python
# 搜索工具
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](docs/ARCHITECTURE.md)

---

## 开发

### 环境设置

```bash
# 克隆项目
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]"
```

### 运行测试

```bash
# 运行所有测试
pytest

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

### 代码格式化

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

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

### 贡献指南

请参阅 [CONTRIBUTING.md](docs/CONTRIBUTING.md)

---

## 文档

- [架构设计](docs/ARCHITECTURE.md) - 系统架构说明
- [API 文档](docs/API.md) - API 接口文档
- [使用示例](examples/) - 代码示例
- [开发流程规范](docs/DEVELOPMENT_WORKFLOW.md) - 开发流程规范
- [任务追踪](docs/TASK.md) - 项目任务追踪
- [变更日志](docs/CHANGELOG.md) - 版本变更记录

---

## 性能指标

| 指标 | 目标值 |
|------|--------|
| 搜索响应时间 | < 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](docs/INSTALLATION.md) - 安装指南
- [USER_GUIDE.md](docs/USER_GUIDE.md) - 用户使用指南
- [CONFIGURATION.md](docs/CONFIGURATION.md) - 配置参数说明
- [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) - 故障排除
- [BEST_PRACTICES.md](docs/BEST_PRACTICES.md) - 最佳实践

### 技术文档
- [API.md](docs/API.md) - API 参考文档
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - 架构设计
- [CLAUDE_CONFIG.md](docs/CLAUDE_CONFIG.md) - Claude 配置指南
- [IDE_CONFIG.md](docs/IDE_CONFIG.md) - IDE 配置指南

### 开发文档
- [CONTRIBUTING.md](docs/CONTRIBUTING.md) - 贡献指南
- [PUBLISHING.md](docs/PUBLISHING.md) - PyPI 发布指南
- [DEVELOPMENT_WORKFLOW.md](docs/DEVELOPMENT_WORKFLOW.md) - 开发流程规范
- [SCRIPTS_GUIDE.md](docs/SCRIPTS_GUIDE.md) - 脚本工具指南

### 项目管理
- [TASK.md](docs/TASK.md) - 项目任务追踪
- [CHANGELOG.md](docs/CHANGELOG.md) - 变更日志

---

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

---

## 致谢

- [Anthropic](https://www.anthropic.com/) - MCP 协议设计
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 服务器框架
- [rank-bm25](https://github.com/dorianbrown/rank_bm25) - BM25 算法实现

---

**项目维护者**: Maric
**项目主页**: [GitHub](https://github.com/maric/RegistryTools)