AI导哈

模块化AI助手平台

一个基于Model Context Protocol（MCP）的模块化AI代理平台，支持运行时工具发现、多工具编排和全栈可观测性，适用于需要动态扩展AI功能的开发场景。

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

使用说明

MCP人工智能助理

通过模型上下文协议可插入的AI工具

一个模块化的生产级AI代理平台，具有运行时工具发现、多工具编排和全栈可观察性。通过启动容器可以添加新功能——无需重新启动代理，无需更改代码，也无需重新部署。

建立在 Anthropic模型上下文协议（MCP），该项目演示了可插拔AI工具的生产级架构：LangChain ReAct代理通过网络发现与MCP兼容的工具服务器，动态构建与LangChain兼容的工具绑定，并编排多步工具链来回答用户查询。

100%本地。 与Ollama一起完全在您的机器上运行。没有API密钥，没有云成本。

主要特点

  • 可插拔工具架构 --每个工具服务器都是一个独立的服务，有自己的容器。在不接触代理的情况下添加、删除或更新工具。
  • 动态工具发现 --代理在运行时通过SSE自动检测MCP服务器。新工具会在服务器启动后几秒钟内出现。
  • 多工具链 --ReAct代理自主地按顺序编排多个工具来回答复杂的查询（例如，搜索网络，然后汇总，然后保存注释）。
  • 智能缓存 --Redis使用可配置的TTL缓存工具结果。重复查询会完全跳过工具调用。
  • 完全可观察性 --Prometheus指标（8种仪器），带有预构建的Grafana仪表板，涵盖工具延迟、成功率、缓存命中率和HTTP性能。
  • 对话记忆 --每个会话的聊天历史记录，以便代理记住各个回合的上下文。
  • PostgreSQL日志记录 --每次工具调用和对话都会使用完整的分析端点进行记录。
  • 一个命令部署 — docker compose up 提起10个集装箱，全部接线。

建筑

🏗️ 建筑

它是如何工作的： 代理通过SSE连接到每个MCP服务器，调用 list_tools() 为了发现可用的工具及其JSON模式，将这些模式转换为与LangChain兼容的Pydantic模型，并将其绑定为ReAct代理的工具。当LLM决定使用工具时，代理打开与相应服务器的SSE连接并调用 call_tool() 与论点。结果通过代理返回给用户。

技术栈

层 技术 目的
LLM Ollama+Qwen3:1.7b 局部推理、工具调用
代理框架 LangChain 使用工具编排重新激活代理
代理的API FastAPI 异步REST API
工具协议 MCP（SSE传输） 标准化工具发现和执行
UI Streamlit 带分析仪表板的聊天界面
缓存 Redis TTL工具结果缓存
数据库 PostgreSQL 对话和工具调用日志
监控 普罗米修斯+格拉法纳 指标收集和可视化
编排 Docker Compose 10容器部署

MCP工具服务器

服务器 端口 工具 描述
笔记管理器 8001 save_note, get_notes, search_notes 带有标签过滤和关键字搜索的持久笔记存储
网络搜索 8002 web_search, fetch_url DuckDuckGo搜索和网页内容提取
文档摘要生成器 8003 summarize_text, extract_key_points 基于LLM的文本摘要和关键点提取
计算器 8004 calculate, convert_units 安全数学评估（基于AST）和单位转换

每个服务器还公开一个 health_check 工具。 总共13个工具 跨4台服务器。

快速开始

先决条件

ollama pull qwen3:1.7b

跑

git clone https://github.com/gulabjamun04/mcp-ai-assistant.git
cd mcp-ai-assistant
docker compose up --build -d

等待约60秒，让所有服务恢复健康，然后：

服务 URL
聊天界面 http://localhost:8501
代理API http://localhost:8000/docs
伯爵 http://localhost:3000 （管理员/管理员）
普罗米修斯 http://localhost:9090

将模型拉入Docker的Ollama

# After containers are up, pull the model into the containerized Ollama
./scripts/pull_model.sh

动态发现演示

查看核心价值主张的实际应用——在代理运行时启动一个新的工具服务器，它会自动获取新的工具：

python scripts/demo.py

Step 1: 10 tools from 3 servers
Step 2: "What is 15% of 250?" → LLM answers alone (no tools)
Step 3: 🚀 Starting calculator container...
Step 4: ✅ 3 new tools discovered → 13 tools from 4 servers
Step 5: Same question → routes to [calculate] tool
Step 6: "Convert 100 km to miles" → [convert_units] tool

零代码更改。零重启。

API终点

方法 端点 描述
POST /chat 发送消息，获取工具使用信息的回复
GET /tools 列出所有发现的MCP工具
POST /tools/refresh 触发手动工具重新发现
GET /health 代理和服务器运行状况
GET /cache/stats 缓存命中/未命中统计数据
DELETE /cache/clear 刷新缓存的工具结果
GET /analytics/tools 工具使用分析
GET /analytics/sessions 会话统计
GET /analytics/recent 最近20次工具调用
GET /metrics 普罗米修斯指标

监控

Grafana仪表板(MCP AI Assistant)是自动配置的，包括：

面板 公制
刀具调用总数 mcp_tool_invocations_total
活动会话 mcp_active_sessions
缓存命中率 mcp_cache_operations_total
可用工具 mcp_available_tools
随时间推移的工具调用 rate(mcp_tool_invocations_total[5m])
平均工具延迟 mcp_tool_duration_seconds
工具成功率 成功率/按工具统计的总数
HTTP请求速率 mcp_http_requests_total
响应时间百分比 P50/P95/P99
错误率 5xx+工具错误

访问地址： http://localhost:3000 （管理员/管理员）。

添加新工具服务器

这种架构的全部意义在于，添加新功能是微不足道的：

1.创建服务器 --使用MCP SDK的单个Python文件：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server", host="0.0.0.0", port=8005)

@mcp.tool()
def my_tool(query: str) -> dict:
    """Tool description for the LLM."""
    return {"result": do_something(query)}

if __name__ == "__main__":
    mcp.run(transport="sse")

2.创建一个Docker文件：

FROM python:3.11-slim
WORKDIR /app
RUN pip install --no-cache-dir mcp
COPY mcp_servers/__init__.py ./mcp_servers/__init__.py
COPY mcp_servers/my_server/ ./mcp_servers/my_server/
EXPOSE 8005
CMD ["python", "-m", "mcp_servers.my_server.server"]

3.添加到 docker-compose.yml 和 agent/config.py.

4.启动它：

docker compose up -d my-server
curl -X POST http://localhost:8000/tools/refresh

5.完成。 代理会立即发现并使用新工具。

项目结构

mcp-ai-assistant/
├── agent/                          # Core AI agent (FastAPI)
│   ├── agent.py                    #   LangChain ReAct agent + session memory
│   ├── cache.py                    #   Redis caching layer
│   ├── config.py                   #   Settings from .env
│   ├── database.py                 #   PostgreSQL logging + analytics
│   ├── main.py                     #   FastAPI app + endpoints
│   ├── mcp_client.py               #   MCP tool registry + discovery
│   └── metrics.py                  #   Prometheus instrumentation
│
├── mcp_servers/                    # MCP tool servers (one per subdirectory)
│   ├── note_manager/               #   Note storage (port 8001)
│   ├── web_search/                 #   Web search + fetch (port 8002)
│   ├── doc_summarizer/             #   Text summarization (port 8003)
│   └── calculator/                 #   Math + unit conversion (port 8004)
│
├── ui/                             # Streamlit chat interface
│   ├── app.py                      #   Entry point
│   ├── api.py                      #   Backend API client
│   └── components/                 #   Chat, sidebar, analytics pages
│
├── monitoring/                     # Observability
│   ├── prometheus/prometheus.yml   #   Scrape config
│   └── grafana/                    #   Dashboard + provisioning
│
├── docker/                         # Docker build files
│   ├── Dockerfile.agent
│   └── init.sql                    #   PostgreSQL schema
│
├── scripts/
│   ├── demo.py                     #   Dynamic discovery demo
│   ├── test_docker.py              #   Docker integration tests
│   ├── pull_model.sh               #   Pull Ollama model into container
│   └── run_local.py                #   Local development launcher
│
├── tests/                          # 161 unit tests
│   ├── test_note_manager.py
│   ├── test_web_search.py
│   ├── test_doc_summarizer.py
│   ├── test_calculator.py
│   ├── test_cache.py
│   └── test_database.py
│
├── docker-compose.yml              # 10-service orchestration
├── requirements.txt
└── .env                            # Environment configuration

测试

# Run all 161 tests
python -m pytest tests/ -v

# Run a specific server's tests
python -m pytest tests/test_calculator.py -v

# Run Docker integration tests (requires docker compose up)
python scripts/test_docker.py

主要特点

运行时工具发现——代理通过SSE自动注册MCP服务器，并动态绑定JSON模式定义的工具。

零停机扩展性——检测到新的工具容器并在几秒钟内可用，无需重新启动代理。

多步工具编排——每个查询最多可重新执行3个以上工具的代理序列（例如，搜索→ 总结→ 坚持）。

分布式架构——4个隔离的MCP服务器，在10个Docker容器中暴露13个工具。

生产可观察性——Prometheus指标（8个仪器），带有Grafana仪表板，涵盖延迟（P50/P95/P99）、工具成功率、缓存指标和HTTP吞吐量。

缓存优化层——基于Redis TTL的缓存减少了冗余的LLM和工具执行。

结构化日志和分析——PostgreSQL支持的具有分析端点的调用日志。

截图

聊天界面

与ReAct代理的多工具对话——在一个会话中搜索网络、保存笔记、总结文档和计算值。

分析仪表板

会话指标、工具使用细分和最近的活动——所有这些都由PostgreSQL日志提供支持。

Grafana监测

实时可观察性：工具延迟、缓存命中率、HTTP性能和活动会话。

监测和可观察性

自动配置的MCP AI Assistant Grafana仪表板包括：

刀具调用总数

活跃会话

缓存命中率

可用工具计数

工具成功率（每个工具）

平均工具延迟

调用率

HTTP请求速率

响应时间百分比（P50/P95/P99）

错误率

所有指标都通过/metrics公开，并由Prometheus抓取。

动态工具发现

一个新的MCP服务器启动，代理自动拿起它的工具——零重启，零代码更改。

▶ 观看动态发现演示

贡献

欢迎捐款。要添加功能，请执行以下操作：

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/my-feature)
  3. 为您的更改编写测试
  4. 确保所有测试通过(python -m pytest tests/ -v)
  5. 打开拉取请求

许可证

该项目根据MIT许可证获得许可。看 许可证 了解详情。

作者

希维什·戴夫

相关 MCP