miwrite MCP 接入指南

1概述

公开目录记录了 8 个付费 pipeline 和 8 个免费 helper。客户端先用 list_model_profiles 查看可用模型，再调用 pipeline。付费 pipeline 可传 module_ids；未传时服务端自动选择至多 6 个知识模块。认证后的远程调用还可传 project_id，服务端会先校验项目归属，再加载受限的项目上下文。

2远程接入参考

以下步骤用于接入生产远程服务。开发时仍可使用 npm run mcp:dev 启动本地 stdio，或安装下文的 Local Skills。

第一步：获取 API Key

在 MCP 控制台 登录并创建 key。默认 key 包含 catalog.read、tools.list、tools.call、pipelines、mcp.read、status.read。包括免费 helper 在内，所有 Hosted MCP 远程调用都需要 API key；纯本地 Skills 不需要登录。

第二步：列出工具

curl -s -X POST https://miwrite.art/api/mcp/remote/rpc \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

第三步：调用工具

curl -s -X POST https://miwrite.art/api/mcp/remote/rpc \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "run_lit_review_pipeline",
      "arguments": {
        "input_text": "Your literature text here...",
        "topic": "Research topic"
      }
    }
  }'

长任务：提交后轮询

付费 pipeline 可使用异步接口，避免客户端连接在长任务期间超时。提交时建议发送稳定且唯一的 Idempotency-Key；同一账号用同一 key 和相同参数重试会返回原任务，不会重复执行或扣费。相同 key 改传其他参数会返回 409 idempotency_conflict。

curl -s -X POST https://miwrite.art/api/mcp/remote/submit \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lit-review-20260819-001" \
  -d '{
    "name": "run_lit_review_pipeline",
    "arguments": {
      "input_text": "Your literature text here...",
      "topic": "Research topic"
    }
  }'

# HTTP 202
{
  "ok": true,
  "request_id": "mcp_req_...",
  "task_id": "task_...",
  "status": "pending",
  "poll_url": "/api/mcp/remote/result/mcp_req_..."
}

curl -i -s \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  https://miwrite.art/api/mcp/remote/result/mcp_req_...

# pending / running: HTTP 202 + Retry-After: 1
# completed / failed: HTTP 200

3接口列表

以下路径相对 https://miwrite.art。发现、状态与目录 GET 接口公开可读；key 管理使用登录会话，远程协议和工具调用使用 Bearer API key。

4工具参考

以下定义实时读取自公开的 /api/mcp/catalog，避免文档与实现漂移。目录公开可读；远程执行必须携带具备对应 scope 的 API key，并受余额、每日额度和速率限制约束。

Pipeline 工具

Helper 工具

5知识库

miwrite 的知识库是一套不断补充的专业内容集合。它不是一个下载区，而是把常用的方法、判断标准、术语说明和例子整理成稳定的内容底座，方便在不同任务里重复使用。

当前包含什么

• 通用方法：材料整理、文本精读、稿件评阅、报告模式、主张与引用核验。
• 专业模块：文献综述、质性资料分析、研究设计压力测试和学术转写。
• 质量标准：不同任务的 rubric、证据判断、问题分级和修改优先级。
• 辅助内容：术语说明、写作风格、精选例子、常见反例。

当前状态

• 目前已经整理出 49 份可复用内容，后续会继续补。
• 这些内容会随着任务需要持续扩充，不是一版写完就封存。
• 知识库的目标不是替你提供材料证据，而是帮助你更稳地读材料、做判断、组织输出。

6示例输出

托管 pipeline 和免费 helper 工具使用不同的成功载荷，但都遵循统一的 `ok/error_code/message` 约束。

{
  "ok": true,
  "tool": "run_lit_review_pipeline",
  "request_id": "mcp_req_xxx",
  "workflow": "literature",
  "report_markdown": "## 文献综述...",
  "material_passport": {
    "access": "redacted",
    "source_count": 2,
    "citation_counts": { "verified": 4, "unverified": 1 }
  },
  "usage": { "totals": { "tokens_in": 1200, "tokens_out": 800 } }
}

{
  "ok": true,
  "tool": "get_workflow_pack",
  "target_tool": "run_lit_review_pipeline",
  "pack": {
    "steps": ["parse", "final"],
    "input_schema": { "...": "..." }
  }
}

7错误规范

MCP 公共契约将错误收敛到少量稳定代码，便于客户端直接处理。

8计费与限额

Hosted MCP 分成免费 helper 和托管模型能力；以下计费与限额适用于生产远程调用。纯本地 Skills 不经过这些 API。

免费 Helper 工具

• list_model_profiles：免费返回当前模型档位、启用状态和服务端默认值
• get_workflow_pack：免费，返回本地执行所需的 prompt / steps / schema，不触发托管付费模型
• search_kb：免费 hosted 知识检索；默认 hybrid_chunk，可 mode=keyword；单独日限额
• search_kb 结果带回 chunk 元数据：chunk_id、source_path、heading、start_line、end_line
• get_template / get_term_map：免费取模板骨架与术语表
• verify_claims：免费本地主张 vs 原文审计（非开放网页查证）
• extract_citations / verify_citations：免费引用抽取与存在性核验

托管模型能力

• 8 个 pipeline 工具通过托管模型运行，按量计费
• 可选 module_ids 指定知识模块；未传时自动选择 ≤6 个 defaults
• 远程调用可选 project_id；项目归属在限额、计费和模型执行前校验，返回结果不会包含项目上下文、Blob key、内部路径或文件字节
• 余额接口和估价接口只用于托管模型模式

模型选择

所有付费 pipeline 都接受可选 model_profile。省略时使用 list_model_profiles 返回的 default_model_profile；调用前应以该工具返回的 enabled 状态为准。

质量、风格与材料控制

• run_review_pipeline 和 run_data_analysis_pipeline 可显式传 cross_model_profile。这会增加一次可计费模型调用；第二模型保留分歧，不取平均，也不覆盖首轮报告。
• 付费 pipeline 可传 passport_access：redacted（默认）、raw 或 verified_only。返回的 material_passport 只含来源标签、计数、引用状态和质量摘要，不返回文稿全文、文件字节、Blob key 或内部路径。
• run_polish_pipeline 可传最多 12,000 字符的 style_reference。它只用于提取语气、节奏和术语偏好，不复制参考文本的事实、论点、引用或专名。

默认限额

9客户端接入

这里描述 Hosted MCP 的客户端契约。不同客户端支持的远程传输、资源和 OAuth 能力并不完全相同；接入时以客户端当前版本和实际握手结果为准。

哪些软件可以接，怎么接

Claude Desktop

客户端版本支持远程 MCP 时，编辑对应的 MCP 配置并加入以下地址。配置格式随客户端版本变化时，以客户端文档为准：

{
  "mcpServers": {
    "miwrite": {
      "type": "url",
      "url": "https://miwrite.art/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_API_KEY"
      }
    }
  }
}

Cursor

可在项目根目录创建 .cursor/mcp.json，或在全局 ~/.cursor/mcp.json 中加入以下配置：

{
  "mcpServers": {
    "miwrite": {
      "url": "https://miwrite.art/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_API_KEY"
      }
    }
  }
}

10Skill System

miwrite provides 9 local skills for Claude Code, Codex, Cursor, and similar local agents. These skills are separate from the hosted MCP service: they do not require login, do not require MIWRITE_API_KEY, and do not use the hosted knowledge base.

Install

curl -fsSL https://raw.githubusercontent.com/lcrxgzl-wq/miwrite.skill/main/install-claude.sh | bash

curl -fsSL https://raw.githubusercontent.com/lcrxgzl-wq/miwrite.skill/main/install-codex.sh | bash

claude mcp add-json miwrite '{"type":"url","url":"https://miwrite.art/mcp","headers":{"Authorization":"Bearer mcp_YOUR_API_KEY"}}'

Local Skill List

11更新日志

完整条目见仓库 CHANGELOG.md。以下记录代码契约的演进，不代表当前生产已启用远程服务；部署可用性以页首状态为准。

2026-08-04

• 新增免费 list_model_profiles，Hosted MCP 客户端可在付费调用前发现默认模型与当前启用状态。
• 8 个 pipeline 的 model_profile 在 tools/list 中提供明确枚举。
• 产品品牌统一为 miwrite，定位扩展为通用文档与知识工作台；学术能力保留为专业 Skills 和模块。

2026-07-12

• Hosted MCP 正式可调用免费 helper：从 2 个扩到 7 个（含 get_template、get_term_map、verify_claims、extract_citations、verify_citations）。
• search_kb 默认 hybrid（关键词 + 本地 TF-IDF）；chunk 元数据保持返回。
• 付费 pipeline 支持可选 module_ids；未传时自动选择 ≤6 个知识模块。
• verify_claims 仅做本地主张 vs 原文审计，不承诺开放网页事实核查。
• 限额：仅 search_kb 使用独立日限额；其余免费 helper 与托管 tools/call 共用日限额桶。
• 本地 Skills 补充 Minimum inputs / Output skeleton，并与 Hosted MCP 继续解耦。

更早

• Hosted MCP 公开 8 个 pipeline 工具。
• search_kb / get_workflow_pack 升级为正式可调用 free tool。
• 公开文档明确 bundle registry、search_kb 与 MCP resources 的统一边界。
• expert_paid 已从公开 model profile 列表移除，但旧输入兼容保留。