AI导哈

MCP服务器与功能SDK

一个基于FastAPI的MCP服务器和功能SDK，用于将工具构建为普通Python函数，支持自动注册和语义化工具发现。

  • by Hevagog
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Hevagog/ap-mcp

使用说明

ap-mcp:mcp服务器+具有自动注册功能的SDK

概述

FastAPI MCP服务器+功能SDK，用于将工具构建为普通Python函数。工具公开了一个FastAPI应用程序，在启动时向MCP服务器自动注册清单，服务器将调用路由到每个函数端点。

主要特点：

  • 语义工具发现 –使用句子转换器(all-MiniLM-L6-v2)将用户查询与工具描述相匹配
  • 本地LLM工具调用 –奥拉玛与 qwen2.5:1.5b (或任何其他工具调用模型)选择并参数化工具
  • 自动注册 –工具在启动时自行注册；无需手动配置
  • 功能SDK –使用装饰器将工具编写为普通Python函数

先决条件

Ollama（必填）

服务器使用 奥拉玛 用于LLM电动工具选择。运行前安装并启动Ollama。

curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama pull qwen2.5:1.5b

注： 如果模型不存在，服务器将在首次启动时自动拉取模型，但这可能需要一些时间。

支持的型号： 任何具有本机工具调用支持的Olama模型都可以工作。通过配置 OLLAMA_MODEL 有人是。

快速开始

cd ap-mcp
ollama serve
just run

建筑

┌─────────────┐     ┌─────────────────────────────────────────────────┐
│     UI      │     │                  MCP Server                     │
│ (port 8501) │────▶│  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
└─────────────┘     │  │ Registry │  │ VectorDB │  │ Orchestrator │   │
                    │  └──────────┘  └──────────┘  └──────────────┘   │
                    │       │              │              │           │
                    │       ▼              ▼              ▼           │
                    │  ┌─────────────────────────────────────────┐    │
                    │  │           Ollama (LLM)                  │    │
                    │  │   Tool selection & response synthesis   │    │
                    │  └─────────────────────────────────────────┘    │
                    └──────────────────────┬──────────────────────────┘
                                           │ HTTP proxy calls
                    ┌──────────────────────▼──────────────────────┐
                    │              External Tools                 │
                    │  ┌────────────────┐  ┌────────────────┐     │
                    │  │ calculator_tool│  │  (your tool)   │     │
                    │  │  (port 5080)   │  │                │     │
                    │  └────────────────┘  └────────────────┘     │
                    └─────────────────────────────────────────────┘

数据流：

  1. 用户通过UI$\rightarrow$Server发送消息 /message 端点
  2. LLMOrchestrator 查询VectorDB以获取语义相似的工具
  3. Ollama选择最佳工具，并通过本机工具调用提取参数
  4. 服务器将调用代理到工具的HTTP端点
  5. Ollama从工具输出中合成自然语言响应

服务和端点

服务 URL 描述
MCP 服务器 http://localhost:5000 中心枢纽
计算器工具 http://localhost:5080 示例工具
用户界面 http://localhost:8501 聊天界面

服务器端点

方法 路径 描述
得到 / 基本状态消息
得到 /health 活体探针
得到 /ready 就绪性探测（由Docker健康检查使用）
职位 /register 工具在启动时在此处发布其清单
得到 /tools 列出已注册的工具（例如。， calculator, calculator.add)
职位 /message 主聊天端点——处理用户消息

工具端点（每个工具）

方法 路径 描述
得到 /manifest 退货 list[Manifest] 对于工具
职位 /invoke/{function_name} 调用特定函数（例如。， /invoke/add)

用户界面

聊天界面可在http://localhost:8501.它连接到MCP服务器，并使用Ollama根据自然语言查询智能地选择和调用已注册的工具。

交互示例：

  • “5加3等于多少？”$\rightarrow$调用 calculator.add(5, 3)
  • “添加10和20”$\rightarrow$调用 calculator.add(10, 20)

创作工具

用以下内容注释函数 @mcp_tool(name=...) 并将其传递给 create_app:

from tool_sdk import mcp_tool, create_app
import uvicorn
import os

@mcp_tool(name="calculator")
def add(a: int, b: int) -> int:
    """Add two integers and return the result."""
    return a + b

@mcp_tool(name="calculator")
def multiply(a: int, b: int) -> int:
    """Multiply two integers and return the product."""
    return a * b

if __name__ == "__main__":
    app = create_app([add, multiply])
    port = int(os.environ.get("TOOL_PORT", "5080"))
    uvicorn.run(app, host="0.0.0.0", port=port)

重要提示： 文档字符串是 关键的 –它们由VectorDB索引以进行语义搜索。编写清晰、描述性的文档字符串，解释函数的作用。

注册工作原理

  1. 工具通过SDK启动其FastAPI应用程序
  2. SDK为每个工具组构建清单：
    • name：组名（来自 @mcp_tool(name=...))
    • base_url: TOOL_PUBLIC_URL env 是
    • methods: [{name, description, parameters, path, http_method}] 由函数签名和文档字符串构建
  3. SDK将清单POST到 ${MCP_SERVER_URL}/register
  4. 服务器验证并存储：
    • 工具组的顶级条目（元数据）
    • 每种方法的代理（例如。， calculator.add)这称为工具 /invoke/{method}
  5. 用于语义搜索的VectorDB中的服务器索引方法描述

配置

环境变量

变量 默认值 描述
OLLAMA_HOST http://localhost:11434 Ollama服务器URL
OLLAMA_MODEL qwen2.5:1.5b LLM刀具选择模型
MCP_SERVER_URL http://mcp_server:5000 服务器URL（用于工具）
TOOL_PUBLIC_URL – 工具的公共URL（用于注册）
TOOL_PORT 5080 工具维修端口
PORT 5000 MCP服务器端口
FLAVOR – 设置为 localdev 用于热重载

使用不同的Olama模型

# Set via environment variable
export OLLAMA_MODEL=llama3.1:8b
just run

# Or in docker-compose.yml
environment:
  - OLLAMA_MODEL=qwen2.5:7b

发展

命令（使用 just)

just run          # Start full stack (Docker Compose)
just build        # Build Docker images
just shell <svc>  # Interactive shell in container (e.g., just shell mcp_server)
just test         # Run pytest
just lint_full    # Run ruff + mypy + fawltydeps
just lint_fix     # Auto-fix linting issues
just dc <cmd>     # Run command inside Docker (e.g., just dc test)

相关 MCP