内容
# 🧠 one-mcp
## 🚀 概述
**one-mcp** 是一个轻量级的 **MCP (Model Context Protocol)** 服务器，使用 **FastAPI** 构建，支持智能工具管理和 API 语义搜索。
它允许您上传、管理和查询 API 工具，使用自然语言 — 通过 `sentence-transformers` 支持现代嵌入模型。
服务器支持多种传输模式（stdio、HTTP 或两者），并提供 REST API 和 MCP 工具接口，以实现最大灵活性。
---
## ✨ 功能
* 🔍 **语义搜索：** 使用 sentence-transformers 嵌入，根据描述性查询查找相关 API 工具。
* 📤 **上传工具：** 通过 JSON 正文或文件上传添加新的 API 工具。
* 🗑️ **删除工具：** 按名称删除特定工具（支持批量删除）。
* 🧾 **工具统计：** 获取存储工具的洞察，包括数量、模型和存储路径。
* 🧹 **工具管理：** 轻松清理、检查或修改您的工具存储。
* ⚡ **FastAPI 后端：** 高性能、异步就绪的后端服务器。
* 🤝 **MCP 兼容性：** 双接口 - REST API 和 MCP 工具，实现无缝集成。
* 🔄 **双传输：** 同时支持 stdio 和 HTTP 传输。
* 💾 **持久化存储：** 工具和嵌入保存到磁盘，自动加载。
* 📊 **结构化日志记录：** 全面的日志记录，带有旋转文件处理程序。
---
## 🧩 项目结构
```
one-mcp/
├── server.py # 主要应用程序入口点，包含服务器编排
├── mcp_server.py # MCP 服务器类，支持多传输
├── api.py # FastAPI 路由和 REST 端点
├── mcp_tools.py # MCP 工具定义和处理程序
├── models.py # Pydantic 模型，用于请求/响应验证
├── tools_store.py # 持久化工具存储，包含嵌入
├── config.py # 服务器配置和参数解析
├── logging_setup.py # 集中式日志配置
├── test_specs.json # 用于测试的示例工具数据集
├── CURLS.md # 用于测试 API 端点的示例 cURL 命令
├── MCP_TOOLS.md # MCP 工具文档
├── requirements.txt # 项目依赖项
├── Dockerfile # Docker 容器化（基于 CPU 的依赖项）
└── README.md # 项目文档（此文件）
```
---
## ⚙️ 安装
### 1. 克隆仓库
```bash
git clone https://github.com/freakynit/one-mcp.git
cd one-mcp
```
### 2. 设置虚拟环境
```bash
python -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
```
### 3. 安装依赖项
```bash
pip install -r requirements.txt
```
依赖项包括：
```
fastapi>=0.104.0
uvicorn>=0.24.0
fastmcp>=0.2.0
python-multipart>=0.0.6
torch==2.4.1
torchvision==0.19.1
torchaudio==2.4.1
sentence-transformers>=2.2.0
scikit-learn>=1.3.0
numpy>=1.24.0
```
---
## 🧠 运行服务器
> **注意：** 服务器首次运行时，它将从 sentence-transformers 下载 `all-MiniLM-L6-v2` 模型。根据您的互联网连接，这可能需要几秒钟。
### 以双传输模式（stdio + HTTP）启动
```bash
python server.py --transport stdio,http --port 8003
```
这启用了 MCP stdio 通信和 HTTP REST API 访问。
### 仅 HTTP 模式
```bash
python server.py --transport http --port 8003
```
### 仅 Stdio 模式（适用于 MCP 客户端）
```bash
python server.py --transport stdio
```
### 直接使用 Uvicorn
```bash
uvicorn server:app --host 0.0.0.0 --port 8003
```
### 配置选项
- `--transport`: 传输模式（stdio、http 或 stdio,http）- 默认：stdio
- `--port`: HTTP 端口号 - 默认：8000
- `--host`: 绑定的主机 - 默认：0.0.0.0
- `--storage_path`: 存储工具嵌入的路径 - 默认：tool_embeddings.json
默认情况下，服务器启动于：
👉 `http://localhost:8003` （当启用 HTTP 传输时）
服务器自动：
- 创建一个 `logs/` 目录用于应用程序日志
- 在启动时从 `tool_embeddings.json` 加载现有工具
- 在任何修改后将工具保存到磁盘
---
## 🧪 测试 API
服务器提供两个接口：
1. **REST API：** 可在 `/api/*` 端点使用（参见 [CURLS.md](./CURLS.md) 获取示例）
2. **MCP 工具：** 可通过 MCP 协议使用（参见 [MCP_TOOLS.md](./MCP_TOOLS.md) 获取文档）
### REST API 端点
所有端点都返回具有适当状态代码的结构化 JSON 响应。
#### 检查服务器状态
```bash
curl http://localhost:8003/api/status
```
#### 通过 JSON 上传工具
```bash
curl -X POST http://localhost:8003/api/tools/upload-json \
-H "Content-Type: application/json" \
-d '{"tools": [{"type": "function", "name": "get_weather", "description": "Get the current weather for a specific city.", "parameters": {"type": "object", "properties": {"city": {"type": "string", "description": "The name of the city to get weather for."}}}}]}'
```
#### 通过文件上传工具
```bash
curl -X POST http://localhost:8003/api/tools/upload-file \
-F "file=@test_tools.json;type=application/json"
```
#### 搜索相似工具
```bash
curl -X POST http://localhost:8003/api/tools/search \
-H "Content-Type: application/json" \
-d '{"query": "weather forecast for a city", "k": 3}'
```
#### 获取统计信息
```bash
curl http://localhost:8003/api/tools/stats
```
#### 删除特定工具
```bash
curl -X DELETE http://localhost:8003/api/tools/delete \
-H "Content-Type: application/json" \
-d '{"tool_names": ["get_weather", "get_news_headlines"]}'
```
#### 清除所有工具
```bash
curl -X DELETE http://localhost:8003/api/tools/clear
```
### MCP 访问
MCP 端点在 `/mcp` 处挂载，用于 HTTP 流式传输模式：
```bash
curl http://localhost:8003/mcp
```
有关完整的 MCP 工具文档，请参见 [MCP_TOOLS.md](./MCP_TOOLS.md)。
有关更全面的测试示例，请参见 [CURLS.md](./CURLS.md)。
---
## 🧰 示例 MCP 配置
与 MCP 客户端（如 Claude Desktop）集成：
```json
{
"mcpServers": {
"one-mcp-server": {
"command": "python",
"args": [
"/absolute/path/to/server.py",
"--transport", "stdio",
"--storage_path", "tool_embeddings.json"
]
}
}
}
```
用于双传输模式（用于 MCP 的 stdio + 用于 REST API 的 HTTP）：
```json
{
"mcpServers": {
"one-mcp-server": {
"command": "python",
"args": [
"/absolute/path/to/server.py",
"--transport", "stdio,http",
"--port", "8004",
"--storage_path", "tool_embeddings.json"
]
}
}
}
```
---
## 🏗️ 架构
### 组件
- **server.py：** 初始化应用程序并启动 MCP 服务器的入口点
- **mcp_server.py：** 处理多传输服务器编排（stdio/HTTP/双）
- **api.py：** FastAPI 应用程序工厂和 REST 端点定义
- **mcp_tools.py：** MCP 工具装饰器和函数实现
- **tools_store.py：** 具有搜索功能的工具嵌入的单例存储
- **models.py：** 用于类型安全性和验证的 Pydantic 模型
- **config.py：** 配置管理和 CLI 参数解析
- **logging_setup.py：** 集中式日志记录，带有旋转文件处理程序
### 工作原理
1. **工具存储：** 工具与其嵌入一起存储，使用 `sentence-transformers`
2. **语义搜索：** 查询嵌入使用余弦相似度进行比较
3. **持久性：** 工具自动保存到 `tool_embeddings.json`
4. **双接口：** 相同的功能可通过 REST API 和 MCP 工具使用
5. **多传输：** 服务器可以同时运行 stdio（用于 MCP 客户端）和 HTTP
---
### 开发
1. 创建 zip：`zip -r one-mcp.zip . -x "*.git/*" -x ".env" -x ".DS_Store" -x ".dockerignore" -x ".gitignore"`
---
## 🧑💻 贡献
欢迎贡献！
要贡献：
1. **Fork** 仓库
2. **创建** 一个新的功能分支（`git checkout -b feature/my-feature`）
3. **提交** 您的更改（`git commit -m "Add my feature"`）
4. **推送** 到您的 fork（`git push origin feature/my-feature`）
5. **提交拉取请求**
在提交之前，请确保：
* 代码通过了 linting 和基本测试。
* 如果需要，您已更新文档。
---
## 📜 许可证
该项目在 **MIT License** 下获得许可 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
---
## 💬 支持
如果您遇到任何问题或有功能请求：
* 在 [GitHub](https://github.com/freakynit/one-mcp/issues) 上打开一个问题
* 或直接联系 [@freakynit](https://github.com/freakynit)。
