AI导哈

功能扩展服务器

基于Model Context Protocol (MCP)的通用功能服务器，为AI提供扩展能力，支持本地和远程双模式运行，并集成ChatBI和Langfuse的观测链路。

  • by Love-Gwen2025
  • Python
  • 混合部署
  • 更新于
在 GitHub 查看 Love-Gwen2025/mcp-server

使用说明

MCP Server - 通用功能服务器

一个基于 Model Context Protocol (MCP) 的通用功能服务器，为 AI 提供扩展能力。

支持 本地模式 (stdio) 与 远程模式 (Streamable HTTP / SSE) 双模式运行，并可将 ChatBI -> MCP -> Langfuse 的观测链路串起来。

✨ 功能

🕐 时间工具

工具 描述
get_current_time 获取指定时区的当前时间
get_timestamp 获取当前 Unix 时间戳
format_timestamp 将时间戳转换为可读格式

📊 ChatBI 数据分析工具

工具 描述
schema_search 基于向量召回 + 关键词检索返回项目相关 Schema
execute_sql 执行只读 PostgreSQL 查询并返回 JSON 结果

🔭 Langfuse 链路观测

  • schema_search 会记录嵌套阶段：分词、Embedding、向量检索、关键词检索、融合裁剪。
  • execute_sql 会记录嵌套阶段：SQL Guardrail 校验、SQL 执行。
  • 当上游 ChatBI 通过 traceparent 和 x-chatbi-* 头透传上下文时，MCP 工具观测会自动挂到同一条 Langfuse Trace 下。

🚀 快速开始

安装依赖

uv sync

本地模式运行

uv run mcp-server

远程模式运行（默认推荐）

uv run mcp-server --remote --transport streamable-http --port 8000

启动后可访问：

  • MCP: http://localhost:8000/mcp
  • Health: http://localhost:8000/health
  • SSE 兼容端点: http://localhost:8000/sse

SSE 兼容模式

uv run mcp-server --remote --transport sse --port 8000

🔌 客户端集成

本地模式配置

适用于 Cursor / Claude Desktop：

{
  "mcpServers": {
    "utility-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server", "run", "mcp-server"]
    }
  }
}

远程模式配置

ChatBI / LangChain4j

直接连接 Streamable HTTP 端点：

http://your-server:8000/mcp

兼容 mcp-remote 的 SSE 客户端

{
  "mcpServers": {
    "utility-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://your-server:8000/sse"]
    }
  }
}

🐳 Docker 部署

使用 Docker Compose（推荐）

docker compose up -d

docker compose logs -f

docker compose down

手动 Docker 命令

docker build -t mcp-server .

docker run -d -p 8000:8000 --name mcp-server mcp-server

docker run -d -p 9000:9000 -e PORT=9000 --name mcp-server mcp-server

🔐 Langfuse 配置

在 .env 中配置：

LANGFUSE_ENABLED=true
LANGFUSE_HOST=https://cloud.langfuse.com
LANGFUSE_PUBLIC_KEY=pk-lf-xxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxx
LANGFUSE_ENVIRONMENT=production
MCP_SERVER_RELEASE=2026.03.09

如果未配置 Langfuse 凭证，服务仍可正常提供 MCP 工具，只是不会上报 tracing 数据。

🧪 开发测试

uv run mcp dev src/mcp_server/server.py
uv run mcp-server --help

📖 架构说明

ChatBI Java Service
    |
    |  traceparent + x-chatbi-* headers
    v
External MCP Server (/mcp)
    |
    |-- schema_search
    |     |-- tokenize
    |     |-- embedding
    |     |-- vector_search
    |     |-- keyword_search
    |     `-- fusion
    |
    `-- execute_sql
          |-- validate
          `-- query

All observations -> Langfuse

📄 许可证

MIT

相关 MCP