Little MCP

小MCP代理🤖

一个简单而强大的本地AI助手，完全在您的机器上运行。Little MCP专为学习和实验而设计，将开源LLM的强大功能与先进的检索增强生成（RAG）相结合，创建了一个智能聊天机器人，可以处理您的个人文档并提供实时信息。

✨ 特性

• 本地LLM集成：由Ollama提供技术支持，实现完全隐私和离线功能
• 选项：克劳德人类学法学硕士：必需的API密钥
• 💻 界面选项：图形网页界面或经典文本界面。
• RAG系统：使用向量嵌入从PDF文档中查询和提取信息
• MCP服务器/客户端架构：演示使用FastAPI实现模型上下文协议
• 双重选择思维/无思维模式：展示思维过程。
• 多工具代理：使用多种工具，包括：

- 文件问答系统（基于RAG） - 本地SQL数据库（Mariadb） - 实时天气信息（OpenWeather API） - 任何城市的当前日期和时间 - 算术计算

• 会话记忆：在整个聊天过程中保持上下文
• 矢量存储持久性：高效地存储和重用文档嵌入

🔧 需求

系统要求

• Python 3.8+
• 奥拉玛 在本地安装并运行
• OpenWeather API密钥（免费层可在 openweathermap.org)

所需Olama型号

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

ollama pull qwen3:4b      (not required when use Claude)
ollama pull nomic-embed-text

📦 安装

请参阅安装文档。

🚀 用法

步骤1：启动MCP服务器

在您的第一个终端中：

python mcp_server.py

您应该看到：

Starting MCP Server ...
INFO:     Uvicorn running on http://127.0.0.1:8000

步骤2：启动MCP客户端

在第二个终端中：

[activate your env if not jet] : source ../.venv/bin/activate]

# Local Ollama silent
python little_mcp.py [graph]

# Local Ollama thinking
python little_mcp.py --think [graph]

# Use Claude (API key required)
python little_mcp.py --provider anthropic [graph]

# Use Claude with thinking mode
python little_mcp.py --provider anthropic --think [graph]

# Override Claude model
python little_mcp.py --provider anthropic --model claude-opus-4-5 [--think]

note: add graph parameter for graphical interface
When use graph interface open your browser and run local URL:
http://127.0.0.1:7860

第三步：开始聊天！

You: What's the weather in Paris?
You: What time is it in Tokyo?
You: What information is in my document about candidates?
You: Calculate ADD, 15, 27

第四步：退出

类型 quit, exit，或 bye 关闭客户端应用程序。

🏗️ 建筑

MCP服务器(mcp_server.py)

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

日期时间工具：

• 使用Nominim对城市名称进行地理编码
• 使用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嵌入文本模型将块转换为向量嵌入
4. 将嵌入存储在Chroma矢量数据库中
5. 提问时检索相关上下文
6. 使用具有检索到的上下文的LLM生成答案

代理架构：

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

🔄 定制

更改LLM模型

编辑 LLM 常数in little_mcp.py:

LLM = "llama2"  # or mistral, mixtral, phi, etc.

添加更多MCP工具

服务器端 (mcp_server.py):

1. 创建您的工具功能：

def get_my_tool(param: str):
    # Your logic here
    return {"result": "data"}

1. 添加API终结点：

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

客户端 (little_mcp.py):

添加到 mcp_tools_config 列表：

{
    "name": "my_tool",
    "description": "Description for the agent to understand when to use this tool",
    "function_name": "get_my_tool"
}

调整RAG参数

修改 little_mcp.py:

# Number of document chunks to retrieve
retriever = self.vector_store.as_retriever(search_kwargs={'k': 3})

# Chunk size and overlap
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000, 
    chunk_overlap=200
)

🗂️ 项目结构

Little_MCP/
├── mcp_server.py          # FastAPI MCP server
├── little_mcp.py          # LangChain client application
├── data/                  # PDF documents directory
├── chroma_db_rag/         # Vector store (auto-generated)
├── .env                   # Environment variables (API keys)
├── requirements.txt       # Python dependencies
└── README.md             # This file

🐛 故障排除

服务器无法启动：

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

天气工具出现故障：

• 确认您的OpenWeather API密钥有效且处于活动状态
• 检查您的互联网连接

矢量存储问题：

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

Ollama连接错误：

• 确保Ollama正在运行(ollama serve)
• 验证模型是否已下载(ollama list)

找不到PDF：

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

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

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

📋 交互示例

You: What's the weather in London?
Assistant: The current weather in London is 12°C with light rain...

You: What time is it in New York?
Assistant: In New York, it's currently 2024-10-22 14:30:15 (Tuesday)...

You: Calculate ADD, 25, 17
Assistant: 42.0

You: What does my document say about candidate scores?
Assistant: Based on the document, the candidates have the following scores...

🤝 贡献

欢迎投稿！这个项目是为学习和实验而设计的。请随意：

• 添加新的工具和功能
• 改进RAG系统
• 增强代理人的推理能力
• 添加对更多文档类型的支持
• 实施额外的MCP端点

📄 许可证

MIT许可证

版权所有（c）2025

特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：

上述版权声明和本许可声明应包含在所有 软件的副本或实质性部分。

软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。

🙏 致谢

内置：

• LangChain -代理框架
• 快速API -API的现代web框架
• 奥拉玛 -本地LLM运行时
• 色度数据库 -矢量数据库
• OpenWeatherMap -天气数据API
• 模型上下文协议（MCP） -通信标准

______________________________________________________________________

版本: 0.1.01

制作❤️ 用于人工智能学习和实验