Metadata-Version: 2.4
Name: registry-tools
Version: 0.2.0
Summary: A universal MCP Tool Registry Server with search capabilities
Project-URL: Homepage, https://github.com/maric/RegistryTools
Project-URL: Documentation, https://github.com/maric/RegistryTools#readme
Project-URL: Repository, https://github.com/maric/RegistryTools
Project-URL: Issues, https://github.com/maric/RegistryTools/issues
Author: Maric
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,mcp,model-context-protocol,tool-registry,tool-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: fastmcp>=0.9.0
Requires-Dist: jieba>=0.42.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rank-bm25>=0.2.2
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: memory-profiler>=0.61.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: embedding
Requires-Dist: numpy>=1.24.0; extra == 'embedding'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'embedding'
Description-Content-Type: text/markdown

# RegistryTools

**版本**: v0.1.1
**更新日期**: 2026-01-09
**独立 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 客户端都可连接

---

> **⚠️ PyPI 发布状态**
>
> **RegistryTools 目前尚未发布到 PyPI**，仅支持从源码本地安装。
>
> | 安装方式 | 命令 | 配置命令 |
> |----------|------|----------|
> | **本地安装**（当前） | `pip install -e .` 或 `uv pip install -e .` | `registry-tools` ✅ |
> | **PyPI 安装**（不可用） | `pip install registry-tools` | - |
> | **uvx 运行**（不可用） | `uvx registry-tools` | - ❌ |
>
> **MCP 配置示例**（本地安装后）:
> ```json
> {
>   "command": "registry-tools",
>   "env": { "REGISTRYTOOLS_DATA_PATH": "~/.RegistryTools" }
> }
> ```

---

## 快速开始

### 安装

```bash
# 本地开发环境（从源码安装）
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`

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

**PyPI 发布后配置** (推荐用于生产):
```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"
    }
  }
}
```

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

**PyPI 发布后配置** (推荐用于生产):
```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"
      }
    }
  }
}
```

**PyPI 发布后配置** (推荐用于生产):
```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
```

**PyPI 发布后配置** (推荐用于生产):
```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`）
- `REGISTRYTOOLS_LOG_LEVEL` - 日志级别（默认: `INFO`）
- `REGISTRYTOOLS_ENABLE_AUTH` - 启用 API Key 认证（默认: `false`）
- `REGISTRYTOOLS_DESCRIPTION` - MCP 服务器描述（可选，默认: 统一的 MCP 工具注册与搜索服务，用于发现和筛选可用工具，提升任务执行工具调用准确性，复杂任务工具调用效率）

**快速示例**:
```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
```

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

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

---

## 高级功能

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

### v0.2.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)
