Writeathon MCP 服务器

这是一个基于MCP协议的Writeathon API服务器，提供了与Writeathon平台集成的MCP服务。

功能特点

• 基于Node.js和TypeScript开发
• 使用MCP协议（Model Context Protocol）提供服务
• 完整支持Writeathon API的所有功能
• 提供REST API接口和MCP服务接口
• 支持空间（Space）管理和多空间操作
• 支持附件（链接、图片）功能
• 支持卡片扩展功能

安装

# 1. 克隆仓库
git clone https://github.com/Hcs66/writeathon-mcp-server.git
cd writeathon-mcp-server

# 2. 安装nodejs
# 确保使用Node.js 20+以上版本，若同时存在多个版本，可先安装nvm并切换

# 安装依赖，确保文件夹有读写权限
npm install

配置

1. 复制.env.example文件为.env.prod
2. 编辑.env.prod文件，填入你的Writeathon用户ID、集成Token（web→设置→集成）

# API配置
API_BASE_URL=https://api.writeathon.cn
WRITEATHON_USER_ID=your_user_id_here
WRITEATHON_TOKEN=your_integration_token_here

# 服务器配置
PORT=3000
HOST=localhost

运行

# 开发模式运行
npm run dev

# 或者构建后运行
npm run build
npm start

• 服务器将在HOST:PORT上运行。
• MCP服务将在HOST:PORT+1上运行。
• MCP SSE地址为HOST:PORT+1/mcp/sse。

在Claude/Trae等平台使用

通过复制mcp.json内容手动创建MCP

其中HOST和PORT为.env配置文件中的HOST和PORT+1，如HOST=localhost,PORT=3000，则url为http://localhost:3001/mcp

{
  "mcpServers": {
    "writeathon": {
      "type": "streamable-http",
      "url": "http://HOST:PORT/mcp",
      "note": "For Streamable HTTP connections, add this URL directly in your MCP Client"
    }
  }
}

API接口

服务器提供以下REST API接口：

• GET /api/me - 获取用户信息
• POST /api/cards - 创建卡片（支持空间和附件）
• GET /api/cards/recent - 获取最近更新的卡片列表（支持空间筛选）
• POST /api/cards/get - 获取卡片
• POST /api/cards/extend - 扩展卡片
• POST /api/writing-pick - 写作拾贝
• GET /api/spaces - 获取空间列表

MCP服务

服务器提供以下MCP服务：

工具（Tools）

• create-card - 创建卡片（支持空间和附件）
• extend-card - 扩展卡片
• get-card - 获取卡片
• get-writing-pick - 写作拾贝
• get-spaces - 获取空间列表

资源（Resources）

• user://me - 用户信息
• recent-cards://exclude_date_title={bool}?space={id} - 最近更新的卡片列表
• cards://{id} - 指定ID的卡片
• writing-pick://{type}?limit={num} - 写作拾贝
• spaces:// - 空间列表

提示（Prompts）

• create-card-prompt - 根据内容创建卡片
• writing-pick-prompt - 获取写作拾贝

新功能说明

空间支持

• 创建卡片时可指定 space 参数，将卡片创建到指定空间
• 获取最近卡片列表时可通过 space 参数筛选指定空间的卡片
• 新增 get-spaces 工具和 spaces:// 资源，支持获取所有空间列表

附件支持

• 创建卡片和扩展卡片时可添加 attachments 参数
• 支持两种附件类型：link（链接）和 image（图片）
• 附件参数为JSON数组字符串，格式如：[{"type":"link","title":"标题","url":"链接地址"}]

扩展卡片

• 新增 extend-card 工具，可在指定父卡片基础上扩展内容
• 支持指定 parent 参数（父卡片ID），将内容扩展到该卡片

使用示例

创建带附件的卡片

// 创建带链接附件的卡片
{
  "title": "我的笔记",
  "content": "这是一条重要笔记",
  "space": "space_id_here",
  "attachments": JSON.stringify([
    {
      "type": "link",
      "title": "参考文章",
      "url": "https://example.com/article",
      "excerpt": "文章摘要"
    }
  ])
}

// 创建带图片附件的卡片
{
  "title": "图片收藏",
  "content": "收藏的图片",
  "attachments": JSON.stringify([
    {
      "type": "image",
      "title": "风景照",
      "url": "https://example.com/image.jpg",
      "content": "图片说明"
    }
  ])
}

扩展卡片

{
  "parent": "parent_card_id",
  "content": "这是扩展的内容",
  "attachments": JSON.stringify([
    {
      "type": "link",
      "title": "扩展资料",
      "url": "https://example.com"
    }
  ])
}

获取指定空间的卡片

// 使用资源
"recent-cards://exclude_date_title=false?space=space_id_here"

// 使用工具
{
  "exclude_date_title": false,
  "space": "space_id_here"
}

许可证

ISC