Beginner's Guide to MCP Servers

MCP 服务入门指南

一个简单的演示项目，帮助编程经验有限的初学者了解并构建模型上下文协议（MCP）服务。

什么是 MCP？

模型上下文协议（MCP）是一种让 AI 助手（如 Claude、ChatGPT 等）连接外部工具和数据源的方式。你可以把它看作一座桥梁，让 AI 能够：

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

本项目包含两个 MCP 服务，展示了不同类型的功能。

包含内容

本项目包含两个 MCP 服务：

1. 励志语录和任务管理服务（motivational_server.py）

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

• 问候工具：一个简单的问候函数
• 随机语录：从本地 JSON 文件中获取励志语录
• 任务管理器：添加、列出和完成本地存储的任务

1. 任意 API 服务（server.py）

演示如何连接外部 API：

• 挪威警方事件：从挪威公共 API 获取实时警情
• 股票市场工具：搜索公司股票代码并获取当前股价（需要免费的 Alpha Vantage 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. 前往 Alpha Vantage 获取免费的 API 密钥
2. 将其设置为环境变量：

   export ALPHA_VANTAGE_API_KEY=your_api_key_here
   

如何与 AI 助手配合使用

与 Claude Desktop 配合使用

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) - 列出任务（可选按“pending”或“complete”筛选）
• 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 规范，了解高级功能