f1-latest-cn-mcp

一个基于 Model Context Protocol (MCP) 的 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 注册三要素

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 解析）

快速开始

安装依赖

npm install

启动服务

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

# 生产模式
npm run start

在 Cursor 中配置

在 Cursor Settings → MCP 中添加服务：

{
  "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

• 示例输入：

{ "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

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