{ "schemaVersion": "1.2.0", "projects": [ { "name": "China Rail MCP", "id": "china-rail", "category": "public-data", "status": "experimental", "source": { "visibility": "public", "repository": "TakeruF/china-rail-mcp", "blueprint": null }, "implementation": { "language": [ "TypeScript" ], "components": [ "MCP server", "public-data provider", "OAuth-protected remote endpoint", "fixture-backed tests" ] }, "protocol": { "transports": [ "stdio", "Streamable HTTP" ] }, "service": { "official_api": false, "mechanism": [ "unauthenticated public 12306 endpoints", "no login or anti-bot bypass" ] }, "auth": { "type": [ "none (local stdio)", "OAuth 2.1 Authorization Code + PKCE (remote)" ], "notes": "No upstream 12306 account credentials are used. Each remote deployment is protected by its operator's private connection secret." }, "capabilities": { "read": true, "write": false, "confirmation_required": false }, "risk": { "level": "medium", "destructive_actions": [], "notes": "Upstream formats and availability can change; no ticket purchase or booking is attempted." }, "tools": [ "get_provider_status", "search_stations", "search_trains", "get_train_details", "get_availability", "compare_trains" ], "media": [ { "id": "chatgpt-without-mcp", "kind": "comparison", "commit": "d352fb746b807c06c4ae2d1a68e6e25e91448e8d", "path": "docs/images/chatgpt-without-mcp.jpg", "capturedAt": "2026-09-03", "i18n": { "en": { "alt": "ChatGPT without China Rail MCP asks the user to verify the result in 12306", "caption": "Without China Rail MCP, ChatGPT could not reliably retrieve the complete evening train list or current seat availability." }, "zh": { "alt": "未接入 China Rail MCP 的 ChatGPT 建议用户前往 12306 核对", "caption": "未接入 China Rail MCP 时，ChatGPT 无法可靠取得晚间完整车次和当前余票。" } } }, { "id": "chatgpt-with-mcp", "kind": "comparison", "commit": "d352fb746b807c06c4ae2d1a68e6e25e91448e8d", "path": "docs/images/chatgpt-with-mcp.jpg", "capturedAt": "2026-09-03", "i18n": { "en": { "alt": "ChatGPT with China Rail MCP lists trains with times, fares, and seat availability", "caption": "With China Rail MCP connected, the same question returned trains, times, reference fares, and seat availability." }, "zh": { "alt": "接入 China Rail MCP 的 ChatGPT 列出车次、时刻、票价和余票", "caption": "接入 China Rail MCP 后，同一问题可返回车次、时刻、参考票价和余票。" } } }, { "id": "12306-reference", "kind": "source-evidence", "commit": "d352fb746b807c06c4ae2d1a68e6e25e91448e8d", "path": "docs/images/12306-reference.jpg", "capturedAt": "2026-09-03", "i18n": { "en": { "alt": "12306 app showing the same Guangzhou South to Changsha South train search", "caption": "The 12306 app was checked at the same time as a point-in-time reference for representative train numbers, times, and starting fares." }, "zh": { "alt": "12306 App 显示同一次广州南到长沙南查询", "caption": "同一时刻使用 12306 App 核对代表性车次、时刻和起始票价，作为当次查询的参考。" } } } ], "i18n": { "en": { "summary": "Search China Railway stations, trains, fares, and seat availability.", "description": "A public-data MCP server for planning rail journeys without login, booking, or anti-bot bypass.", "limitations": "Upstream public endpoints may change. It never purchases or books tickets." }, "zh": { "summary": "查询中国铁路车站、车次、票价和余票信息。", "description": "面向行程规划的公共数据 MCP 服务器，不需要登录，不提供购票或绕过反爬的功能。", "limitations": "上游公开接口可能变更；本项目不购买或预订车票。" } } }, { "name": "ColorOS Calendar Bridge", "id": "coloros-calendar", "category": "device-bridge", "status": "experimental", "source": { "visibility": "private", "repository": "TakeruF/coloros-calendar-bridge", "blueprint": "blueprints/device-bridge" }, "implementation": { "language": [ "Kotlin", "TypeScript" ], "components": [ "Android app", "CalendarContract data source", "mock MCP server", "future authenticated device relay" ] }, "protocol": { "transports": [ "Android CalendarContract", "Streamable HTTP MCP", "CalDAV" ] }, "service": { "official_api": true, "mechanism": [ "Android CalendarContract", "standards-based CalDAV", "mock bridge contract" ] }, "auth": { "type": [ "Android runtime permission", "planned device-bound credential", "app-specific password for optional CalDAV" ], "notes": "The committed MCP server is mock mode; no production relay or OAuth issuer is included." }, "capabilities": { "read": true, "write": true, "confirmation_required": true }, "risk": { "level": "high", "destructive_actions": [ "create/update/delete event", "sync", "conflict resolution" ], "notes": "Delete and conflict resolution must be disabled by default in a real relay." }, "tools": [ "list_calendars", "list_events", "create_event", "update_event", "delete_event" ], "i18n": { "en": { "summary": "An experimental bridge between Android CalendarContract, CalDAV, and MCP.", "description": "A private device-integration implementation with a public blueprint for a permission-aware, device-bound bridge.", "limitations": "The committed MCP server is mock mode; production relays and OAuth issuers are not included." }, "zh": { "summary": "连接 Android CalendarContract、CalDAV 与 MCP 的实验性桥接项目。", "description": "一个私有设备集成实现，并提供具备权限意识和设备绑定特性的公开桥接蓝图。", "limitations": "已提交的 MCP 服务器为模拟模式；不包含生产中继或 OAuth 签发器。" } } }, { "name": "iCloud Mail MCP", "id": "icloud-mail", "category": "mail", "status": "stable", "source": { "visibility": "private", "repository": "TakeruF/icloud-mail-mcp", "blueprint": "blueprints/secure-mail-mcp" }, "implementation": { "language": [ "TypeScript" ], "components": [ "MCP server", "IMAP client", "SMTP sender", "OAuth-enabled HTTP adapter" ] }, "protocol": { "transports": [ "stdio", "Streamable HTTP", "IMAP over TLS", "SMTP over TLS" ] }, "service": { "official_api": false, "mechanism": [ "standards-based IMAP/SMTP", "Apple app-specific password" ] }, "auth": { "type": [ "app-specific password", "deployment OAuth" ], "notes": "Production OAuth configuration remains private." }, "capabilities": { "read": true, "write": true, "confirmation_required": true }, "risk": { "level": "high", "destructive_actions": [ "send", "move", "Trash", "flag mutation", "draft mutation" ], "notes": "Permanent deletion is intentionally unsupported." }, "tools": [ "list_mailboxes", "search_mail", "get_message", "send_mail" ], "i18n": { "en": { "summary": "A private, safety-first iCloud Mail MCP implementation with a public blueprint.", "description": "The production implementation is private; the provider-neutral secure-mail blueprint enables compatible implementations without private source access.", "limitations": "Production OAuth and account configuration are private. Permanent deletion is not supported." }, "zh": { "summary": "一个以安全为先的私有 iCloud Mail MCP 实现，并提供公开蓝图。", "description": "生产实现保持私有；与提供商无关的安全邮件蓝图让开发者无需访问私有源码也能构建兼容实现。", "limitations": "生产 OAuth 与账户配置为私有；不支持永久删除。" } } }, { "name": "QQ Mail MCP", "id": "qq-mail", "category": "mail", "status": "beta", "source": { "visibility": "private", "repository": "TakeruF/qq-mail-mcp", "blueprint": "blueprints/secure-mail-mcp" }, "implementation": { "language": [ "TypeScript" ], "components": [ "MCP server", "provider interface", "QQ IMAP/SMTP provider", "HTTP adapter" ] }, "protocol": { "transports": [ "stdio", "Streamable HTTP", "IMAP over TLS", "SMTP over TLS" ] }, "service": { "official_api": false, "mechanism": [ "standards-based IMAP/SMTP", "QQ Mail authorization code" ] }, "auth": { "type": [ "mail authorization code", "deployment OAuth" ], "notes": "Host and deployment configuration are account-specific." }, "capabilities": { "read": true, "write": true, "confirmation_required": true }, "risk": { "level": "high", "destructive_actions": [ "send", "archive", "Trash", "mark read", "draft mutation" ], "notes": "Trash is recoverable; permanent deletion is not exposed." }, "tools": [ "search_mail", "get_message", "read_attachment", "send_mail" ], "i18n": { "en": { "summary": "A private QQ Mail MCP implementation built on a reusable secure-mail design.", "description": "A provider-specific mail implementation with a public blueprint for the security and provider-boundary model.", "limitations": "Host and deployment configuration are account-specific; permanent deletion is not exposed." }, "zh": { "summary": "基于可复用安全邮件设计的私有 QQ Mail MCP 实现。", "description": "这是一个针对提供商的邮件实现，并公开安全与提供商边界设计蓝图。", "limitations": "主机和部署配置因账户而异；不提供永久删除。" } } } ], "blueprints": [ { "id": "secure-mail-mcp", "path": "blueprints/secure-mail-mcp", "relatedProjects": [ "icloud-mail", "qq-mail" ], "i18n": { "en": { "name": "Secure Mail MCP", "summary": "A provider-neutral blueprint for building safety-first mail MCP servers.", "solves": "It separates mail-provider adapters from MCP policy and confirmation boundaries.", "architecture": "MCP server, provider interface, IMAP/SMTP adapters, and an explicit confirmation gate.", "included": "Threat model, environment example, test plan, and implementation guidance.", "excluded": "Private production code, credentials, deployment OAuth configuration, and provider account data.", "security": "Read operations are conservative; sending and mutations require explicit confirmation.", "uses": "Building an account-scoped IMAP/SMTP MCP server." }, "zh": { "name": "安全邮件 MCP", "summary": "用于构建安全优先邮件 MCP 服务器的、与提供商无关的蓝图。", "solves": "将邮件提供商适配器与 MCP 策略及确认边界分离。", "architecture": "MCP 服务器、提供商接口、IMAP/SMTP 适配器和明确的确认门。", "included": "威胁模型、环境变量示例、测试计划和实现指南。", "excluded": "私有生产代码、凭据、部署 OAuth 配置和提供商账户数据。", "security": "读取操作保持保守；发送和变更必须明确确认。", "uses": "构建账户范围内的 IMAP/SMTP MCP 服务器。" } } }, { "id": "device-bridge", "path": "blueprints/device-bridge", "relatedProjects": [ "coloros-calendar" ], "i18n": { "en": { "name": "Device Bridge", "summary": "A blueprint for permission-aware MCP bridges to local device data.", "solves": "It defines a boundary between an AI-facing MCP server and privileged device APIs.", "architecture": "MCP transport, device-bound relay, permissioned platform adapter, and audit-friendly mutation policy.", "included": "Boundary model, transport guidance, and safety constraints.", "excluded": "Production device relay code, user data, and device credentials.", "security": "Device permissions are explicit; destructive operations need confirmation and safe defaults.", "uses": "Connecting AI to calendar, sensor, or platform data through a local bridge." }, "zh": { "name": "设备桥接", "summary": "用于连接本地设备数据的、具备权限意识的 MCP 桥接蓝图。", "solves": "定义面向 AI 的 MCP 服务器与特权设备 API 之间的边界。", "architecture": "MCP 传输、设备绑定中继、受权限保护的平台适配器和便于审计的变更策略。", "included": "边界模型、传输指南和安全约束。", "excluded": "生产设备中继代码、用户数据和设备凭据。", "security": "设备权限必须明确；破坏性操作需要确认并采用安全默认值。", "uses": "通过本地桥接将 AI 连接到日历、传感器或平台数据。" } } } ], "clients": [ { "id": "chatgpt", "name": "ChatGPT", "supportStatus": "supported-with-plan", "transports": [ "Streamable HTTP", "Secure MCP Tunnel" ], "localStdio": false, "remoteMcp": true, "writeTools": "workspace-only", "officialUrls": [ "https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt-beta" ], "i18n": { "en": { "name": "ChatGPT", "account": "Pro supports custom read/fetch MCP connections. Full MCP, including write actions, requires Business, Enterprise, or Edu and workspace administration.", "recommended": "Deploy a private HTTPS MCP with OAuth. Use Secure MCP Tunnel when the server must remain on a private network.", "limitations": "Do not rely on Plus for an individually developed MCP: the dedicated Developer Mode requirements do not clearly list it. Custom apps are added on the web; Agent mode does not use them." }, "zh": { "name": "ChatGPT", "account": "Pro 可连接仅含 read/fetch 的自定义 MCP。包含写入操作的完整 MCP 需要 Business、Enterprise 或 Edu，并受工作区管理。", "recommended": "部署带 OAuth 的私有 HTTPS MCP；若服务器必须留在私网，可使用 Secure MCP Tunnel。", "limitations": "不要默认 Plus 就支持个人自建 MCP：官方文档并未写明 Plus 具备专用 Developer Mode。自定义应用需在网页端添加，Agent 模式不会调用该类应用。" } } }, { "id": "qwen-code", "name": "Qwen Code", "supportStatus": "supported", "transports": [ "stdio", "Streamable HTTP", "SSE" ], "localStdio": true, "remoteMcp": true, "writeTools": "supported", "officialUrls": [ "https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/", "https://qwenlm.github.io/qwen-code-docs/en/users/configuration/auth/" ], "i18n": { "en": { "name": "Qwen Code", "account": "MCP itself needs no premium client tier. Model access still requires a Coding Plan or API provider; the free Qwen OAuth tier ended on April 15, 2026.", "recommended": "Use stdio for a local server or Streamable HTTP for a hosted server, configured with qwen mcp add or settings.json.", "limitations": "The consumer qwen.ai web chat does not document the same arbitrary MCP URL flow as Qwen Code." }, "zh": { "name": "千问 Code（Qwen Code）", "account": "启用 MCP 本身不需要高级客户端套餐，但使用模型仍需要 Coding Plan 或者对接对应 API 服务商；Qwen OAuth 免费层已于 2026-04-15 结束。", "recommended": "本地服务器使用 stdio，托管服务器使用 Streamable HTTP，并通过 qwen mcp add 或 settings.json 配置。", "limitations": "普通 qwen.ai 网页对话，不具备千问 Code 那样直接添加任意 MCP URL 的能力。" } } }, { "id": "doubao-chat", "name": "Doubao chat", "supportStatus": "not-documented", "transports": [], "localStdio": null, "remoteMcp": null, "writeTools": "not-documented", "officialUrls": [], "i18n": { "en": { "name": "Doubao chat", "account": "No general account path for adding an arbitrary self-hosted MCP URL is currently documented.", "recommended": "Use TRAE for a developer client, or Coze and Volcengine products for a hosted agent using Doubao models.", "limitations": "Built-in or partner MCP availability in a product does not prove that arbitrary custom servers can be added." }, "zh": { "name": "豆包", "account": "目前官方没有公开普通账号添加任意自建 MCP URL 的功能流程。", "recommended": "开发客户端优先使用 TRAE；使用豆包模型的托管智能体可考虑扣子或火山引擎产品。", "limitations": "产品内置或合作方 MCP 可用，不代表用户可以添加任意自定义服务器。" } } }, { "id": "trae", "name": "TRAE", "supportStatus": "supported", "transports": [ "stdio", "remote MCP" ], "localStdio": true, "remoteMcp": true, "writeTools": "supported", "officialUrls": [ "https://developer.volcengine.com/articles/7497876519193165875" ], "i18n": { "en": { "name": "TRAE", "account": "MCP servers can be selected from the marketplace or added manually. Model quota, region, and client availability remain separate conditions.", "recommended": "Use TRAE instead of the consumer Doubao chat app when manually connecting a developer-owned MCP server.", "limitations": "Recheck the current client UI and quota before setup because product availability can change." }, "zh": { "name": "TRAE", "account": "可以从市场选择或手动添加 MCP Server；但模型额度、服务地区、客户端可用性为独立约束条件。", "recommended": "需要手动连接开发者自建 MCP 时，优先使用 TRAE，而不是普通豆包聊天应用。", "limitations": "产品可用性可能变化，配置前应重新核对当前客户端界面和额度。" } } }, { "id": "coze", "name": "Coze", "supportStatus": "supported", "transports": [ "HTTPS MCP" ], "localStdio": false, "remoteMcp": true, "writeTools": "supported", "officialUrls": [ "https://docs.coze.cn/guides_create_a_plugin_based_on_mcp" ], "i18n": { "en": { "name": "Coze", "account": "Creating an MCP-based plugin is free; hosting, model, and third-party service usage can still cost money. Private-network connections are an enterprise-tier feature.", "recommended": "Provide an HTTPS hostname, choose no auth, service token/API key, or OAuth, then test and publish the plugin before using it in an agent or workflow.", "limitations": "A bare IP address is not accepted as the plugin URL. Workspace administrators can restrict feature and resource visibility." }, "zh": { "name": "扣子（Coze）", "account": "创建基于 MCP 的插件本身免费，但托管、模型和第三方服务仍可能收费；私网连接属于企业级功能。", "recommended": "提供 HTTPS 域名，选择无认证、Service Token/API key 或 OAuth，试运行并发布后再用于智能体或工作流。", "limitations": "插件 URL 不接受裸 IP；工作区管理员可以限制功能和资源可见性。" } } }, { "id": "claude", "name": "Claude", "supportStatus": "supported-with-plan", "transports": [ "desktop extension", "Streamable HTTP", "SSE" ], "localStdio": true, "remoteMcp": true, "writeTools": "supported", "officialUrls": [ "https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp", "https://support.anthropic.com/en/articles/11725091-when-to-use-desktop-and-web-connectors" ], "i18n": { "en": { "name": "Claude", "account": "Local desktop extensions are available to free Claude Desktop users. Remote custom connectors require Pro, Max, Team, or Enterprise.", "recommended": "Use a desktop extension for local access or add a remote connector URL in Settings > Connectors.", "limitations": "On Team and Enterprise, an Owner or Primary Owner must first add the organization connector." }, "zh": { "name": "Claude", "account": "Claude Desktop 免费用户可使用本地桌面扩展；远程自定义连接器需要 Pro、Max、Team 或 Enterprise。", "recommended": "本地访问使用桌面扩展，远程访问则在 Settings > Connectors 中添加连接器 URL。", "limitations": "Team / Enterprise 版本，需要 Owner 或 Primary Owner 预先添加组织连接器。" } } }, { "id": "gemini-spark", "name": "Gemini Spark", "supportStatus": "limited-preview", "transports": [ "remote MCP" ], "localStdio": false, "remoteMcp": true, "writeTools": "confirmation-required", "officialUrls": [ "https://support.google.com/gemini/answer/17209137" ], "i18n": { "en": { "name": "Gemini Spark", "account": "Requires Gemini Spark access, age 18 or over, a personal Google Account, Keep Activity enabled, and current eligibility in the United States.", "recommended": "Add the MCP URL from Gemini web Connected Apps, then use the connection in Spark on web or mobile.", "limitations": "Currently English-only and not a general connection path for accounts in Japan, or for work and school accounts." }, "zh": { "name": "Gemini Spark", "account": "需要拥有 Gemini Spark 使用权限、年满 18 周岁、使用个人 Google 账号、开启 Keep Activity，同时满足美国地区可用限制。", "recommended": "从 Gemini 网页版 Connected Apps 添加 MCP URL，之后在网页或移动端的 Spark 中使用。", "limitations": "目前仅支持英语，不是日本账号或工作、学校账号的通用连接方式。" } } } ], "guides": [ { "id": "china-rail", "projectId": "china-rail", "updatedAt": "2026-09-03", "sourceCommit": "d4ac43f60067cdbadc1e891940242a249a2e53f5", "i18n": { "en": { "title": "Set up China Rail MCP", "intro": "A beginner-friendly path from choosing a client to proving that a real railway query works. You do not need a 12306 account or programming experience.", "startTitle": "Start with one decision", "startIntro": "Where do you want to use China Rail MCP? The answer determines how it connects.", "routes": [ { "id": "local", "title": "On this computer", "summary": "Choose local stdio. Your AI client starts China Rail MCP on the same computer.", "bestFor": "The easiest and safest first setup. No public server, domain, or secret is required.", "needs": [ "A desktop MCP client that supports local stdio", "Git", "Node.js 20 or later", "npm 10 or later" ], "cost": "China Rail MCP itself is free. Your AI client or model provider may charge separately.", "steps": [ "Choose a desktop client that supports local stdio. Qwen Code, TRAE, and Claude Desktop are common routes; check the client guide before installing anything.", "Copy the AI setup request below into a coding AI that can use your terminal and files.", "Allow it to install missing software, restart an app, or change settings only after it explains the action.", "Do not accept “the build passed” as completion. Ask for a real get_provider_status call and a real train search from the configured client." ], "prompt": "Install and configure China Rail MCP on this computer until I can make a real Chinese railway query from the AI client I currently use. Repository: https://github.com/TakeruF/china-rail-mcp\n\nPerform the work instead of only giving me a tutorial. First identify the operating system, AI/MCP client, and whether Git, Node.js, and npm are available. If the target client is unclear, ask only that question. Read the latest README and self-hosting guide. Explain and ask before installing software, using administrator access, restarting a GUI app, or changing security settings.\n\nClone the repository into a stable location without overwriting existing work. Run npm ci and npm run verify. Find the absolute paths to Node.js and dist/index.js, then add a local stdio server named china-rail using the configuration format actually supported by my client. Preserve all existing settings. Local mode needs no .env, 12306 account, cookie, or secret; never ask me for them.\n\nReload the client as required. Prove the setup from the configured client by calling get_provider_status, searching for 上海虹桥 with search_stations, and then searching for trains from 上海虹桥 to 杭州东 on a date inside the current sales window. Distinguish a working local connection from a temporary 12306 live-query failure. Finish by reporting the installation path, client configuration changed, verification result, actual MCP tool result, and one example question I can ask next. Do not commit or push repository changes.", "manualTitle": "Prefer to do it yourself?", "manualIntro": "Run these commands in a terminal. Then add the absolute dist/index.js path to your client's stdio MCP configuration.", "commands": [ "git clone https://github.com/TakeruF/china-rail-mcp.git", "cd china-rail-mcp", "npm ci", "npm run verify" ], "success": [ "npm run verify passes", "The client lists China Rail MCP or its six tools", "get_provider_status returns through the client", "A current station or train query returns through the client" ], "troubleshooting": [ "A silent npm start is normal: an stdio server waits for the client over standard input/output.", "If the client cannot find Node.js, use the absolute path returned by command -v node.", "If only the live query fails, the MCP connection may still be correct; check provider status and the current 12306 availability separately." ] }, { "id": "remote", "title": "On a phone or across devices", "summary": "Choose a private remote deployment. Your AI client connects to China Rail MCP over HTTPS.", "bestFor": "Phone access or multiple devices. This route has more account, hosting, authentication, and possible cost requirements.", "needs": [ "GitHub and Vercel accounts", "An AI client account that supports custom remote MCP", "A stable HTTPS deployment", "Private authentication and OAuth" ], "cost": "China Rail MCP is free, but hosting, model usage, or the required client plan may cost money.", "steps": [ "Check the client compatibility guide first. Consumer chat apps do not all accept arbitrary custom MCP servers.", "Copy the remote setup request below into a coding AI that can use both a browser and terminal.", "Approve account sign-in, cloud project creation, charges, and Production deployment only after their impact is explained.", "Verify deployment, account connection, and the phone tool call as three separate results." ], "prompt": "Deploy China Rail MCP as a private personal remote service and continue until I can make a real Chinese railway query from my phone's AI client. Repository: https://github.com/TakeruF/china-rail-mcp\n\nPerform the work instead of only giving me a tutorial. Read the latest README, self-hosting guide, and the current client's official remote-MCP documentation. Confirm that my GitHub, Vercel, and AI client accounts have the required features. Explain and ask before charges, cloud project creation, account sign-in, or Production deployment.\n\nClone the repository safely, run npm ci and npm run verify, and do not modify or push its source. Create a personal Vercel project. Generate a strong unique MCP_HTTP_BEARER_TOKEN and store it only as a masked Production environment variable. Never show it in source, .env, Git, chat, screenshots, logs, or the final report.\n\nDeploy the current main commit to Production and use its stable HTTPS hostname. Run npm run smoke:http -- https://ACTUAL_HOST/api. Confirm health and OAuth metadata return 200, and that unauthenticated /api/mcp returns the expected 401 with discovery information. This 401 proves authentication is active.\n\nConnect https://ACTUAL_HOST/api/mcp using the flow actually supported by my current client and complete OAuth. First call get_provider_status and search_stations on web or desktop. Then open a new conversation on the phone with the same account, enable the connection, and search for trains from 上海虹桥 to 杭州东 on a date inside the sales window. Report deployment success, account connection success, and mobile tool-call success separately. Never make the server public or remove authentication as a workaround. Finish by reporting only the project name, HTTPS MCP URL without secrets, deployment and tool-call results, possible cost points, and how to revoke access.", "manualTitle": "What the hosted setup must produce", "manualIntro": "The implementation repository contains the exact deployment and OAuth details. These are the milestones to check.", "commands": [ "npm ci", "npm run verify", "npm run smoke:http -- https://YOUR_HOST/api", "Connect https://YOUR_HOST/api/mcp in the supported AI client" ], "success": [ "The Production deployment and unauthenticated smoke test pass", "OAuth completes and a web or desktop client can call a tool", "The same account can see the connection on the phone", "A real tool call succeeds from a new phone conversation" ], "troubleshooting": [ "An unauthenticated 401 from /api/mcp is expected when discovery information is present.", "A successful deployment does not prove that the account or phone app supports custom MCP.", "If mobile access is missing, check the client version, account plan, region, staged rollout, and workspace policy. Do not disable authentication." ] } ], "safetyTitle": "Keep these boundaries", "safety": [ "China Rail MCP is read-only. It does not log in, book, purchase, solve CAPTCHAs, or bypass restrictions.", "Local mode never needs a 12306 account, user cookie, API key, or .env file.", "Keep remote deployments private. Never paste the bearer secret into chat or publish it in a repository.", "Verify important travel information in an official 12306 channel because public upstream formats and availability can change." ], "glossaryTitle": "Three terms in plain language", "glossary": [ { "term": "MCP", "definition": "A standard that lets an AI client call tools supplied by another program." }, { "term": "stdio", "definition": "A local connection: the desktop client starts the MCP program on the same computer." }, { "term": "remote MCP", "definition": "A hosted HTTPS connection used by cloud clients and, when supported, phone apps." } ] }, "zh": { "title": "配置 China Rail MCP", "intro": "面向新手的完整路径：先选择客户端，再完成连接，并用一次真实铁路查询确认可用。不需要 12306 账号，也不要求编程经验。", "startTitle": "先做一个选择", "startIntro": "你想在哪里使用 China Rail MCP？这决定了连接方式。", "routes": [ { "id": "local", "title": "在这台电脑上使用", "summary": "选择本地 stdio。AI 客户端会在同一台电脑上启动 China Rail MCP。", "bestFor": "这是最简单、最安全的首次配置方式，不需要公网服务器、域名或密钥。", "needs": [ "支持本地 stdio 的桌面 MCP 客户端", "Git", "Node.js 20 或更高版本", "npm 10 或更高版本" ], "cost": "China Rail MCP 本身免费；AI 客户端或模型提供商可能另外收费。", "steps": [ "选择支持本地 stdio 的桌面客户端。千问 Code（Qwen Code）、TRAE 和 Claude Desktop 都是常见方案；安装前先看客户端指南。", "把下面的 AI 配置请求完整复制给能够操作终端和文件的编程 AI。", "安装缺失软件、重启应用或修改设置时，只在 AI 说明影响后再允许。", "不要把“构建通过”当成完成；必须从已配置客户端实际调用 get_provider_status 并查询车次。" ], "prompt": "请在这台电脑上安装并配置 China Rail MCP，直到我能在当前使用的 AI 客户端中实际查询中国铁路数据。项目地址：https://github.com/TakeruF/china-rail-mcp\n\n请直接执行操作，不要只给教程。先识别操作系统、AI/MCP 客户端，以及 Git、Node.js、npm 是否可用。若目标客户端不明确，只问我这一个问题。阅读最新 README 和自托管指南。安装软件、使用管理员权限、重启图形界面应用或修改安全设置前，先说明影响并征得同意。\n\n把仓库克隆到稳定位置，不要覆盖现有工作。运行 npm ci 和 npm run verify。取得 Node.js 和 dist/index.js 的绝对路径，按照当前客户端真实支持的格式添加名为 china-rail 的本地 stdio 服务器，并保留全部现有设置。本地模式不需要 .env、12306 账号、Cookie 或密钥，不要向我索取。\n\n按需重新加载客户端。必须从已配置客户端调用 get_provider_status，用 search_stations 查询“上海虹桥”，再查询售票窗口内上海虹桥到杭州东的车次。区分“本地连接正常”和“12306 实时查询暂时失败”。最后只报告安装位置、修改的客户端配置、验证结果、真实 MCP 工具调用结果，以及一个之后可以直接询问的问题。不要提交或推送仓库改动。", "manualTitle": "想自己操作？", "manualIntro": "在终端依次运行这些命令，再把 dist/index.js 的绝对路径填入客户端的 stdio MCP 配置。", "commands": [ "git clone https://github.com/TakeruF/china-rail-mcp.git", "cd china-rail-mcp", "npm ci", "npm run verify" ], "success": [ "npm run verify 通过", "客户端能列出 China Rail MCP 或其六个工具", "能从客户端调用 get_provider_status", "能从客户端完成一次当前车站或车次查询" ], "troubleshooting": [ "npm start 没有输出通常是正常的：stdio 服务器正在通过标准输入输出等待客户端。", "若客户端找不到 Node.js，请使用 command -v node 返回的绝对路径。", "若只有实时查询失败，MCP 连接仍可能正常；请分别检查 provider status 和当前 12306 可用性。" ] }, { "id": "remote", "title": "在手机或多台设备上使用", "summary": "选择私人远程部署。AI 客户端会通过 HTTPS 连接 China Rail MCP。", "bestFor": "适合手机或多设备使用，但账号、托管、认证和费用条件更多。", "needs": [ "GitHub 和 Vercel 账号", "支持自定义远程 MCP 的 AI 客户端账号", "固定 HTTPS 部署", "私人认证和 OAuth" ], "cost": "China Rail MCP 免费，但托管、模型用量或客户端所需套餐可能收费。", "steps": [ "先查看客户端兼容性指南。并非所有普通聊天应用都能添加任意自定义 MCP。", "把下面的远程配置请求完整复制给能够操作浏览器和终端的编程 AI。", "账号登录、创建云项目、产生费用或进入 Production 前，先了解影响再确认。", "分别验证部署、账号连接和手机工具调用，不能用前一项推断后一项。" ], "prompt": "请把 China Rail MCP 部署为仅供我个人使用的远程服务，并一直完成到我能在手机上的 AI 客户端实际查询中国铁路数据。项目地址：https://github.com/TakeruF/china-rail-mcp\n\n请直接执行操作，不要只给教程。阅读最新 README、自托管指南和当前客户端的官方远程 MCP 文档。确认我的 GitHub、Vercel 和 AI 客户端账号是否具备所需功能。产生费用、创建云项目、登录账号或进入 Production 前，先说明影响并征得同意。\n\n安全克隆仓库，运行 npm ci 和 npm run verify，不要修改或推送源码。创建个人 Vercel 项目。生成唯一且强度足够的 MCP_HTTP_BEARER_TOKEN，只存为隐藏的 Production 环境变量。绝对不要把它显示在源码、.env、Git、聊天、截图、日志或最终报告中。\n\n部署当前 main 到 Production，并使用固定 HTTPS 主机名。运行 npm run smoke:http -- https://实际主机/api，确认 health 和 OAuth 元数据返回 200，未认证的 /api/mcp 按预期返回带发现信息的 401；这个 401 表示认证已生效。\n\n按照当前客户端真实支持的流程连接 https://实际主机/api/mcp 并完成 OAuth。先在网页或桌面端调用 get_provider_status 和 search_stations，再用同一账号在手机新对话中启用连接，查询售票窗口内上海虹桥到杭州东的车次。分别报告部署成功、账号连接成功和手机工具调用成功。不要通过公开服务器或移除认证来绕过限制。最后只报告项目名、不含密钥的 HTTPS MCP URL、部署和工具调用结果、可能收费的位置，以及撤销访问的方法。", "manualTitle": "远程配置必须达到什么结果", "manualIntro": "实现仓库提供准确的部署和 OAuth 细节。请逐项确认以下里程碑。", "commands": [ "npm ci", "npm run verify", "npm run smoke:http -- https://你的主机/api", "在受支持的 AI 客户端中连接 https://你的主机/api/mcp" ], "success": [ "Production 部署和未认证冒烟测试通过", "OAuth 完成，网页或桌面客户端能调用工具", "同一账号能在手机上看到连接", "能从手机新对话实际调用工具" ], "troubleshooting": [ "若 /api/mcp 的未认证 401 带有发现信息，这是预期结果。", "部署成功不代表账号或手机应用一定支持自定义 MCP。", "手机端不可用时，检查客户端版本、账号套餐、地区、逐步开放状态和工作区策略；不要关闭认证。" ] } ], "safetyTitle": "请保持这些边界", "safety": [ "China Rail MCP 只读，不登录、不购票、不处理验证码，也不绕过限制。", "本地模式绝不需要 12306 账号、用户 Cookie、API key 或 .env 文件。", "远程部署必须保持私有，不要把 bearer 密钥粘贴到聊天或提交到仓库。", "上游公开格式和可用性可能变化，重要出行信息请在 12306 官方渠道再次核对。" ], "glossaryTitle": "用简单语言理解三个词", "glossary": [ { "term": "MCP", "definition": "一种标准，让 AI 客户端可以调用另一个程序提供的工具。" }, { "term": "stdio", "definition": "本地连接方式：桌面客户端在同一台电脑上启动 MCP 程序。" }, { "term": "远程 MCP", "definition": "托管在 HTTPS 上的连接方式，供云端客户端以及受支持的手机应用使用。" } ] } } } ], "clientCompatibilityCheckedAt": "2026-09-03" }