小型MCP代理 🤖

一个简单而强大的本地AI助手，完全在您的机器上运行。旨在学习和实验，Little MCP结合了开源大语言模型（LLM）的力量与先进的检索增强生成（RAG）系统，创建了一个能够处理您个人文档并提供实时信息的智能聊天机器人。

✨ 特性

• 本地LLM集成：由Ollama驱动，确保完全隐私和离线功能
• RAG系统：使用向量嵌入查询和提取PDF文档中的信息
• MCP服务器/客户端架构：通过FastAPI演示模型上下文协议的实现
• 多工具代理：访问多个工具包括：
  • 基于RAG的文档问答系统
  • 实时天气信息（OpenWeather API）
  • 任何城市的当前日期和时间
  • 算术计算
• 对话记忆：在整个聊天会话中维持上下文
• 向量存储持久化：高效地存储和重用文档嵌入

🔧 要求

系统要求

• Python 3.8+
• 安装并本地运行Ollama
• OpenWeather API密钥（免费层级可在openweathermap.org获取）

必需的Ollama模型

在运行应用程序之前下载这些模型：

ollama pull qwen3:1.7b
ollama pull nomic-embed-text

📦 安装

1. 克隆仓库

   wget https://github.com/ricard1406/Little_MCP/archive/refs/heads/main.zip
   unzip main.zip
   mv Little_MCP-main Little_MCP
   cd Little_MCP
   

2. 安装依赖

    python3 -m venv .venv
    source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
    pip install requests pydantic langchain==0.0.354 langchain-community langchain-core chromadb pypdf fastapi uvicorn requests python-dotenv pytz timezonefinder geopy
    但如果您获取的是little_mcp_2.py版本
    pip install langchain-core langchain-community langchain-ollama langchain-text-splitters langgraph fastapi uvicorn requests python-dotenv pytz timezonefinder geopy
   

3. 设置环境变量

   编辑.env文件：

   cd source
   [如果您想要实时天气，请打开您喜欢的编辑器并设置您的openweather密钥]
   [vi] .env
   OPENWEATHER_API_KEY=your_api_key_here
   
   注意：您的本地.data文件夹包含示例文档
   

   从OpenWeatherMap获取您的免费API密钥

4. 准备您的PDF文档

   打开data目录并将您的PDF文件放置于此：

   cd data
   # 将您的PDF复制到./data/
   

5. 配置客户端应用

   编辑little_mcp.py中的常量：

   SERVER_URL = "http://127.0.0.1:8000"
   PDF_DOCUMENT_PATH = "./data/your-document.pdf"
   LLM = "qwen3:1.7b"  # 或任何其他Ollama模型
   

🚀 使用

第一步：启动MCP服务器

在第一个终端中：

python mcp_server.py

您应该看到：

正在启动MCP服务器...
INFO:     Uvicorn正在运行于http://127.0.0.1:8000

服务器提供了以下端点：

• GET / - 健康检查
• GET /get_datetime?myParam=<城市> - 获取当前日期/时间
• GET /get_weather?myParam=<城市> - 获取天气信息
• GET /get_calc?myParam=<操作> - 执行计算

第二步：启动MCP客户端

在第二个终端中：

[如果尚未激活环境，请激活它]：source ../.venv/bin/activate
python little_mcp.py

第三步：开始聊天！

您：巴黎的天气如何？
您：东京现在几点？
您：我的文档中关于候选人的信息是什么？
您：计算ADD, 15, 27

第四步：退出

输入quit、exit或bye以关闭客户端应用。

🏗️ 架构

MCP服务器（mcp_server.py）

基于FastAPI的服务器提供了各种工具的RESTful端点：

日期时间工具：

• 使用Nominatim进行城市名称地理编码
• 使用TimezoneFinder确定时区
• 返回当前日期、时间和星期几

天气工具：

• 集成OpenWeather API
• 返回当前天气状况（公制单位）
• 包括温度、湿度和天气描述

计算器工具：

• 支持基本算术运算（ADD、SUB、MUL、DIV）
• 输入格式："OPERATION, NUM1, NUM2"
• 示例："ADD, 5, 3"返回8

MCP客户端（little_mcp.py）

基于LangChain的客户端协调多个组件：

RAG系统：

1. 使用PyPDFLoader加载您的PDF文档
2. 将文档分割成可管理的块
3. 使用Ollama的nomic-embed-text模型将块转换为向量嵌入
4. 将嵌入存储在Chroma向量数据库中
5. 当您提问时检索相关上下文
6. 使用带有检索上下文的LLM生成答案

代理架构：

• 分析您的查询以确定最佳工具
• 将关于您的文档的问题路由到RAG系统
• 使用MCP服务器工具获取实时信息
• 当没有合适的工具时回退到通用知识
• 维护对话历史以实现上下文感知响应

🔄 自定义

更改LLM模型

编辑little_mcp.py中的LLM常量：

LLM = "llama2"  # 或mistral, mixtral, phi等

添加更多MCP工具

服务器端（mcp_server.py）：

1. 创建您的工具函数：

def get_my_tool(param: str):
    # 您的逻辑在此处
    return {"result": "数据"}

2. 添加API端点：

@app.get("/get_my_tool")
def api_get_my_tool(myParam: str = Query(...)):
    结果 = get_my_tool(myParam)
    return 结果

客户端端（little_mcp.py）：

添加到mcp_tools_config列表：

{
    "name": "my_tool",
    "description": "代理理解何时使用此工具的描述",
    "function_name": "get_my_tool"
}

调整RAG参数

修改little_mcp.py：

# 检索的文档块数量
retriever = self.vector_store.as_retriever(search_kwargs={'k': 3})

# 块大小和重叠
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000, 
    chunk_overlap=200
)

🗂️ 项目结构

Little_MCP/
├── mcp_server.py          # FastAPI MCP服务器
├── little_mcp.py          # LangChain客户端应用
├── data/                  # PDF文档目录
├── chroma_db_rag/         # 向量存储（自动生成）
├── .env                   # 环境变量（API密钥）
├── requirements.txt       # Python依赖
└── README.md             # 此文件

🐛 故障排除

服务器无法启动：

• 检查端口8000是否已被占用
• 验证您的.env文件中包含API密钥

天气工具失败：

• 确认您的OpenWeather API密钥有效且活跃
• 检查您的互联网连接

向量存储问题：

• 删除chroma_db_rag目录以从头开始重建

Ollama连接错误：

• 确保Ollama正在运行（ollama serve）
• 验证模型已下载（ollama list）

未找到PDF：

• 验证PDF_DOCUMENT_PATH中的路径
• 确保文件存在于data目录中

客户端无法连接到服务器：

• 确认服务器正在端口8000上运行
• 检查SERVER_URL配置

📋 示例交互

您：伦敦现在的天气如何？
助手：伦敦当前的天气是12°C，有轻微降雨...

您：纽约现在几点？
助手：在纽约，目前的时间是2024-10-22 14:30:15（星期二）...

您：计算ADD, 25, 17
助手：42.0

您：我的文档中关于候选人分数说了什么？
助手：根据文档，候选人有以下分数...

🤝 贡献

欢迎贡献！该项目旨在学习和实验。您可以自由：

• 添加新的工具和能力
• 改进RAG系统
• 提升代理的推理能力
• 添加对更多文档类型的支援
• 实现额外的MCP端点

📄 许可证

MIT许可证

版权所有 (c) 2025

特此授予任何人获得该软件及其相关文档文件副本的权利（以下简称“软件”），无限制地使用、复制、修改、合并、发布、分发、再许可和/或销售该软件的副本，并允许接收该软件的人这样做，但须符合以下条件：

上述版权声明和本许可通知应包含在所有副本或软件的重要部分中。

软件按“原样”提供，不附带任何形式的保证，包括但不限于适销性、特定用途适用性和非侵权性的默示保证。在任何情况下，作者或版权持有者均不对因软件或其使用或其他交易引起的任何索赔、损害或其他责任承担任何责任，无论是合同行为、侵权行为还是其他行为。

🙏 致谢

构建于：

• LangChain - 代理框架
• FastAPI - 现代API网络框架
• Ollama - 本地LLM运行时
• ChromaDB - 向量数据库
• OpenWeatherMap - 天气数据API
• 模型上下文协议（MCP） - 通信标准

---

版本：0.1.01

为AI学习和实验制作，充满爱心