# f1-latest-cn-mcp

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 F1 赛事资讯服务，让 AI 助手（如 Cursor、Claude Desktop）能够实时查询 F1 官网最新新闻。

## 什么是 MCP？

MCP（Model Context Protocol）是一种开放协议，定义了 **AI 模型与外部工具** 之间的通信标准。

```
用户提问 → AI 模型 → 调用 MCP Tool → MCP 服务执行 → 返回结果 → AI 组织回复 → 用户看到答案
```

通俗地说：MCP 就像是给 AI 装上了"手"，让它能够操作外部服务、获取实时数据，而不仅仅依赖训练数据。

### 核心概念

| 概念 | 说明 |
|------|------|
| **MCP Server** | 工具服务端，注册并暴露 Tool 给 AI 使用 |
| **MCP Client** | AI 客户端（如 Cursor），负责发现和调用 Tool |
| **Tool** | 一个具体的功能单元（如"查询 F1 新闻"），包含名称、描述、参数定义、执行逻辑 |
| **Transport** | 通信传输层（本项目使用 stdio：stdin 接收请求，stdout 返回响应） |

### Tool 注册三要素

```javascript
server.registerTool(
  "tool_name",         // 1. 工具名称（AI 通过此名称调用）
  {
    title: "...",       // 2a. 展示名称
    description: "...", // 2b. 功能描述（★ AI 据此决定何时调用，写得越清楚越好）
    inputSchema: {},    // 2c. 参数定义（Zod schema，AI 据此传参）
  },
  handler              // 3. 执行函数（接收参数，返回结果）
);
```

## 功能特性

- **F1 新闻查询** — 实时爬取 F1 官网最新文章，支持分页
- **自动注册 Tool** — 在 `src/tools/` 下新增文件即可接入，零耦合扩展
- **统一错误处理** — 所有 Tool 自动 try-catch，返回标准错误码
- **统一日志输出** — 时间戳 + 等级 + 元数据，输出到 stderr（不干扰 MCP 协议）
- **预置工具层** — 封装 `axios`（HTTP）/ `dayjs`（时间）/ `cheerio`（HTML 解析）

## 快速开始

### 安装依赖

```bash
npm install
```

### 启动服务

```bash
# 开发模式（文件变更自动重启）
npm run dev

# 生产模式
npm run start
```

### 在 Cursor 中配置

在 Cursor Settings → MCP 中添加服务：

```json
{
  "mcpServers": {
    "f1-latest-cn": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "/your/path/to/f1-latest-cn-mcp"
    }
  }
}
```

配置后重启 Cursor，即可在对话中使用：

- "查询最新 F1 新闻"
- "查看下一页"

## 目录结构

```
src/
├── server.js                 # 入口：创建 MCP 服务、连接传输层
├── config/
│   ├── constants.js          # 全局常量（服务名称、超时、日志级别）
│   └── error-codes.js        # 统一错误码定义与映射
├── tools/
│   ├── index.js              # Tool 自动注册（扫描目录、动态 import）
│   ├── health.js             # health_check —— 健康检查
│   ├── time.js               # format_time —— 时间格式化
│   └── f1-latest.js          # f1_latest_news —— F1 新闻查询（支持分页）
└── utils/
    ├── http.js               # axios 封装（统一超时配置）
    ├── logger.js             # 日志工具（输出到 stderr）
    ├── response.js           # MCP 标准响应构造器
    └── safe-tool.js          # Tool 安全执行包装器（统一 try-catch + 日志）
```

## 内置 Tool

### 1. `health_check`

健康检查，确认 MCP 服务可用。

- **参数**：无
- **返回**：服务状态 + 时间戳

### 2. `format_time`

格式化时间，支持自定义输入和格式。

- **参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `input` | string | 否 | 输入时间，默认当前时间 |
| `format` | string | 否 | 输出格式，默认 `YYYY-MM-DD HH:mm:ss` |

- **示例输入**：

```json
{ "input": "2026-02-28 10:00:00", "format": "YYYY/MM/DD HH:mm" }
```

### 3. `f1_latest_news`

获取 F1 官网最新新闻列表，支持分页。

- **参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `page` | number | 否 | 页码，默认 1 |

- **返回**：Markdown 格式的文章列表（标题、发布时间、链接）
- **AI 行为**：自动将英文标题翻译为中文；用户说"下一页"时自动递增 page

## 扩展指南：如何新增一个 Tool

### 第 1 步：创建文件

在 `src/tools/` 下新建文件，如 `weather.js`。

### 第 2 步：编写 Tool

```javascript
import * as z from "zod/v4";
import { createSafeToolHandler } from "../utils/safe-tool.js";
import { createSuccessResult } from "../utils/response.js";

export const registerWeatherTool = (server) => {
  server.registerTool(
    "get_weather",                              // 工具名称
    {
      title: "Get Weather",
      description: "查询指定城市的天气",         // AI 据此决定何时调用
      inputSchema: {
        city: z.string().describe("城市名称"),   // AI 据此传参
      },
    },
    createSafeToolHandler("get_weather", async ({ city }) => {
      // 你的业务逻辑...
      const weather = await fetchWeather(city);
      return createSuccessResult({ city, weather });
    }),
  );
};
```

### 第 3 步：重启服务

无需修改其他文件，自动注册机制会自动发现并注册新 Tool。

### Tool 开发要点

| 要点 | 说明 |
|------|------|
| **description 写清楚** | AI 根据 description 决定何时调用你的 Tool，含糊则 AI 不知道什么时候该用 |
| **参数 .describe() 写清楚** | AI 根据参数描述来填充参数值 |
| **用 createSafeToolHandler 包裹** | 自动 try-catch + 日志，无需手动处理异常 |
| **返回用 createSuccessResult** | 确保返回值符合 MCP 协议格式 |
| **可在 description 中嵌入 AI 指令** | 如"请翻译为中文"、"用户说 XX 时做 YY"，间接控制 AI 行为 |

## 技术栈

| 依赖 | 用途 |
|------|------|
| `@modelcontextprotocol/sdk` | MCP 协议 SDK（服务端 + 传输层） |
| `axios` | HTTP 请求 |
| `cheerio` | 服务端 HTML 解析（类 jQuery API） |
| `dayjs` | 日期时间处理 |
| `zod` | 参数 Schema 定义与校验 |

## 许可证

MIT