Gritai Basic MCP Server

MCP服务器入门指南

一个简单的演示项目，帮助初学者以最少的编码经验理解和构建模型上下文协议（MCP）服务器。

什么是MCP？

模型上下文协议（MCP）是AI助手（如Claude、ChatGPT等）连接到外部工具和数据源的一种方式。将其视为一座桥梁，使人工智能能够：

• 从互联网获取实时信息
• 与本地文件和应用程序交互
• 代表您执行特定任务

此项目包含两个示例MCP服务器，演示了不同类型的功能。

包含什么

该项目包括两台MCP服务器：

1.励志语录和任务管理器服务器(motivational_server.py)

演示本地文件操作和任务管理：

• Hello工具：简单的问候功能
• 随机报价：从本地JSON文件获取励志名言
• 任务管理器：添加、列出并完成本地存储的任务

1.任何API服务器(server.py)

演示如何连接到外部API：

• 挪威警方事件：从挪威公共API获取实时警察事件
• 股票市场工具：搜索公司股票行情并获取当前股价（需要免费的AlphaVantage API密钥）

先决条件

在开始之前，请确保您已经：

• 您的计算机上安装了Python 3.11或更高版本

安装和设置

步骤1:克隆或下载此项目

将此项目下载到您的计算机，然后导航到终端中的项目文件夹。

步骤2：创建虚拟环境

python -m venv .venv

步骤3：激活虚拟环境

在macOS/Linux上：

source .venv/bin/activate

在Windows上：

.venv\Scripts\activate

步骤4：安装依赖项

pip install -e .

步骤5：（可选）建立股票市场API

要使用股票市场功能，您需要Alpha Vantage提供的免费API密钥：

1. 首选 阿尔法Vantage 并获得一个免费的API密钥
2. 将其设置为环境变量：

   export ALPHA_VANTAGE_API_KEY=your_api_key_here

如何使用AI助手

使用克劳德桌面

1. 打开您的Claude Desktop配置文件
2. 添加服务器配置：

{
  "mcpServers": {
    "HelloServer": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "/path/to/your/project",
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "server.py"        
      ],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "demo"
      }
    }
  }
}

与其他MCP客户端

有关连接说明，请参阅MCP客户端的文档。

可用工具

主服务器工具

• hello() -返回问候信息
• get_police_incidents() -从挪威获取最新警方事件
• get_incidents_by_district(district_name) -从特定警区获取事件
• get_incidents_by_municipality(municipality_name) -从特定市政当局获取事件
• search_stock_ticker(company_name) -搜索公司的股票代码
• get_stock_price(symbol) -获取股票代码的当前股价

激励服务器工具

• hello() -返回问候信息
• get_random_quote() -返回一个随机的励志名言
• add_task(description) -将新任务添加到任务列表中
• list_tasks(status_filter) -列出任务（可选按“待处理”或“已完成”筛选）
• mark_task_complete(task_id) -将任务标记为已完成

项目结构

gritai-basic-mcp-server/
├── server.py              # Main server with API integrations
├── motivational_server.py # Server with local file operations
├── quotes.json           # Motivational quotes database
├── tasks.json            # Task storage file
├── pyproject.toml        # Project configuration
└── README.md            # This file

自定义服务器

添加新报价

编辑 quotes.json 添加你自己的励志名言：

{
  "quote": "Your inspiring quote here",
  "author": "Quote Author"
}

添加新工具

要向任一服务器添加新工具，请使用 @mcp.tool() 装饰师：

@mcp.tool()
def your_new_tool(parameter: str) -> str:
    """Description of what your tool does."""
    # Your tool logic here
    return "Result"

故障排除

常见问题

“找不到模块”错误

• 确保您已激活虚拟环境
• 跑 pip install -e . 安装依赖项

库存工具API错误

• 检查您的Alpha Vantage API密钥设置是否正确
• 免费API密钥有速率限制

找不到文件错误

• 确保从项目目录运行服务器
• 检查一下 quotes.json 和 tasks.json 存在

获取帮助

• 检查 MCP文件
• 查看代码注释以了解实现细节
• 服务器包括错误处理功能，以帮助识别问题

后续步骤

一旦你熟悉了这些例子：

1. 尝试修改现有工具
2. 添加您自己的API集成
3. 创建与本地文件交互的工具
4. 探索MCP规范以了解高级功能