内容
# fastworks-mcp
[](https://github.com/igun997/fastworks-mcp/actions/workflows/ci.yml)
[](https://github.com/igun997/fastworks-mcp/releases/latest)
Fastwork 自由职业者 CLI 和 MCP 服务器。登录一次，将会话保存到磁盘，然后从终端或 AI 代理管理订单、服务、聊天、职位竞标、奖励、提现、统计数据和在线状态。
两个二进制文件：
| 二进制文件 | 用途 |
| --- | --- |
| `fastworks` | 面向人类和脚本的 CLI |
| `fastworks-mcp` | 面向 AI 代理的标准输入输出 MCP 服务器 |
## 要求
- Go 1.23 或更新版本
- Fastwork 卖家账户（与卖家网页应用使用的相同端点）
## 安装
每个版本都附带预编译的二进制文件（linux 和 darwin on amd64/arm64，windows amd64）：
```bash
VERSION=$(curl -fsSL https://api.github.com/repos/igun997/fastworks-mcp/releases/latest | grep -m1 '"tag_name"' | cut -d'"' -f4)
curl -fsSL "https://github.com/igun997/fastworks-mcp/releases/download/${VERSION}/fastworks-mcp_${VERSION}_linux_amd64.tar.gz" | tar -xz
cd "fastworks-mcp_${VERSION}_linux_amd64"
./fastworks version
```
每个版本还附带 `checksums.txt`；使用 `sha256sum -c checksums.txt` 验证。
使用 Go 工具链：
```bash
go install github.com/igun997/fastworks-mcp/cmd/fastworks@latest
go install github.com/igun997/fastworks-mcp/cmd/fastworks-mcp@latest
```
从源代码：
```bash
git clone git@github.com:igun997/fastworks-mcp.git
cd fastworks-mcp
make build # bin/fastworks 和 bin/fastworks-mcp，版本从 git 标记
make check # gofmt + vet + 测试
```
## 快速开始
```bash
bin/fastworks login --email you@example.com # 提示输入密码
bin/fastworks whoami # 确认会话
bin/fastworks orders --status selling # 今日工作
bin/fastworks chat rooms --unread # 谁在等待
bin/fastworks presence # 每日在线签到
```
然后将 AI 代理指向同一会话：
```bash
bin/fastworks-mcp # 标准输入输出 MCP 服务器，59 个工具
```
## 登录
```bash
fastworks login --email you@example.com # 提示输入密码
fastworks login --email you@example.com --password-stdin < pass.txt
fastworks whoami
```
登录流程与卖家网页应用镜像：
1. `POST api.fastwork.id/auth/v2/login` 返回一次性 `authorization_code`。
2. `GET seller.fastwork.id/callback?code=…` 设置 `accessToken` cookie（一个约 1 年的 JWT）。
3. `POST seller.fastwork.id/api/user` 确认会话并返回配置文件。
会话状态（令牌、过期时间、cookie、设备 ID）存储在 `~/.config/fastworks/session-<profile>.json` 中，目录 `0700`，文件 `0600`。使用 `--profile NAME` 来管理多个账户。
`--save-credentials` 将电子邮件和密码存储在该文件中，以便 CLI 和 MCP 服务器可以在令牌被拒绝时自动重新登录。密码以明文写入；任何可以读取该文件或其备份的人都可以以您的身份登录。可以使用 `fastworks session forget-credentials` 删除它。
## CLI
```bash
fastworks orders --status selling # 活动订单（状态 2）
fastworks orders --status approval # 等待买家批准（状态 4）
fastworks notifications --orders-only --limit 10
fastworks services # 列出服务
fastworks service get --id ID --section basic|packages|media|metadata|detail
fastworks service create # 草稿，占据一个产品槽
fastworks service upload --id ID --file cover.jpg
fastworks service update --id ID --file payload.json
fastworks service submit --id ID
fastworks service visible --id ID --show=false
fastworks service delete --id ID --yes # 不可逆
fastworks service auto-message --id ID --message "Hi, thanks for reaching out"
fastworks service categories
fastworks service schema # 确切的可写字段、限制、工作流程
fastworks chat rooms --unread
fastworks chat messages --room ROOM_ID --limit 30
fastworks chat send --room ROOM_ID --message "On it, sending a draft tonight"
fastworks chat send --room ROOM_ID --image progress.png --message "Update hari ini"
fastworks chat send --room ROOM_ID --file build.zip
fastworks chat media --room ROOM_ID [--files]
fastworks chat read --room ROOM_ID
fastworks chat unread
fastworks order get --code SOD105EI # 订单在聊天中：状态、买家、报价
fastworks order works --order ORDER_ID # 已经发送的可交付成果
fastworks order submit-work --code SOD105EI --room ROOM_ID --file build.zip --link https://drive…
fastworks order quotation create --order ORDER_ID --file quotation.json
fastworks order quotation cancel --order ORDER_ID
fastworks order templates # 已保存的报价模板
fastworks order milestones --master ORDER_ID
fastworks order review --order ORDER_ID --rating 5 --comment "Brief jelas"
fastworks withdrawals --balance
fastworks withdrawals --month 7 --year 2026
fastworks withdrawals --detail WITHDRAWAL_ID
fastworks jobboard quota # 已使用/允许的竞标
fastworks jobboard jobs --search website --open
fastworks jobboard job --id JOB_ID
fastworks jobboard bid --job JOB_ID --product SERVICE_ID \
--description-file pitch.txt --budget 4000000 --days 21 --brief-url https://example.com
fastworks jobboard my-bids
fastworks jobboard withdraw --offer BID_ID --yes
fastworks rewards points
fastworks rewards missions --open
fastworks rewards claim # 声明每个开放的任务
fastworks rewards catalog --affordable
fastworks rewards redeem --reward REWARD_ID --yes
fastworks stats # 评分、响应时间、签到
fastworks stats --monthly # 收入系列
fastworks stats --products # 每个产品的性能
fastworks stats --product PRODUCT_ID
fastworks presence # 每日在线签到
fastworks presence --every 30m # 保持签到
fastworks watch # 实时事件为 JSON 行
fastworks watch --webhook https://example.com/hook --events new_message_received,order_updated
fastworks session show --check
fastworks logout
```
退出机制，用于没有专用命令的端点：
```bash
fastworks api POST /api/v4/product.getMyServices --data '{}'
fastworks api GET /order/v2/orders --query limit=10 --include
fastworks graphql --query 'query { user { credits, pending_withdrawal_credits } }'
```
全局标志在子命令之前或之后都有效：`--profile`、`--json`。
### 服务更新负载
`service update` 发送部分补丁；只有您包含的键会更改。
```json
{
"title": "Android 应用开发",
"description": "React Native 应用加 Play Store 上传",
"category_id": "0856f9bb-…",
"subcategory_id": "…",
"base_price": 1500000,
"images": [{ "url": "https://…", "thumbnail_url": "https://…", "caption": null }],
"packages": [
{
"name": "基本",
"price": 1500000,
"active": true,
"description": "APK 和源代码",
"delivery_times": 30,
"revision_times": 1,
"is_revision_times_unlimited": false,
"deliverables": []
}
]
}
```
典型的新建服务流程：`service create` → `service upload`（返回 `url` 和 `thumbnail_url`）→ `service update`，包含标题、描述、类别、价格、图片、包 → `service submit`。
完整的字段参考、限制和验证规则：[docs/service-fields.md](docs/service-fields.md)，或 `fastworks service schema` / 运行时 `fastwork_service_schema` MCP 工具。
## MCP 服务器
```bash
fastworks-mcp # 标准输入输出，默认启用实时聊天套接字
fastworks-mcp --profile work --presence 30m
```
### 客户端配置
使用二进制文件的绝对路径。以下客户端都使用相同的服务器块。
Claude Desktop — Linux 上的 `~/.config/Claude/claude_desktop_config.json`，macOS 上的 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"fastwork": {
"command": "/home/you/bin/fastworks-mcp",
"args": ["--presence", "30m"]
}
}
}
```
Cursor — `~/.cursor/mcp.json`（或项目内的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"fastwork": {
"command": "/home/you/bin/fastworks-mcp",
"args": []
}
}
}
```
pi — `~/.pi/agent/mcp.json`，`directTools` 在网关包装器之外公开工具：
```json
{
"mcpServers": {
"fastwork": {
"command": "/home/you/bin/fastworks-mcp",
"args": ["--presence", "30m"],
"directTools": true
}
}
}
```
VS Code（GitHub Copilot 代理模式）— `.vscode/mcp.json`：
```json
{
"servers": {
"fastwork": {
"type": "stdio",
"command": "/home/you/bin/fastworks-mcp",
"args": []
}
}
}
```
单独的账户拥有单独的配置文件，每个服务器条目：
```json
{
"mcpServers": {
"fastwork-main": { "command": "/home/you/bin/fastworks-mcp", "args": ["--profile", "main"] },
"fastwork-agency": { "command": "/home/you/bin/fastworks-mcp", "args": ["--profile", "agency"] }
}
}
```
标志：`--profile NAME` 选择会话配置文件，`--realtime=false` 禁用聊天 WebSocket，`--presence 30m` 保持卖家在线连胜，`--version` 打印构建版本。
在启动服务器之前运行 `fastworks login`；MCP 服务器读取相同的会话文件，并在没有有效令牌时拒绝需要身份验证的工具。
工具：
| 区域 | 工具 |
| --- | --- |
| 会话 | `fastwork_whoami` |
| 订单 | `fastwork_orders_list`、`fastwork_notifications` |
| 服务 | `fastwork_service_schema`、`fastwork_services_list`、`fastwork_service_get`、`fastwork_service_create_draft`、`fastwork_service_update`、`fastwork_service_submit`、`fastwork_service_set_visible`、`fastwork_service_delete`、`fastwork_service_auto_message`、`fastwork_service_upload_media`、`fastwork_categories_list` |
| 聊天 | `fastwork_chat_rooms`、`fastwork_chat_room`、`fastwork_chat_messages`、`fastwork_chat_send`、`fastwork_chat_send_image`、`fastwork_chat_send_file`、`fastwork_chat_media_list`、`fastwork_chat_mark_read`、`fastwork_chat_unsend`、`fastwork_chat_unread`、`fastwork_chat_events` |
| 订单在聊天中 | `fastwork_order_get`、`fastwork_order_list`、`fastwork_order_works`、`fastwork_order_submit_work`、`fastwork_order_milestones`、`fastwork_order_review_buyer` |
| 提案 | `fastwork_quotation_schema`、`fastwork_quotation_create`、`fastwork_quotation_cancel`、`fastwork_quotation_templates` |
| 资金 | `fastwork_wallet`、`fastwork_withdrawals_list`、`fastwork_withdrawal_details` |
| 统计 | `fastwork_seller_stats`、`fastwork_income_monthly`、`fastwork_product_performance`、`fastwork_service_stats` |
| 职位板 | `fastwork_jobboard_jobs`、`fastwork_jobboard_job`、`fastwork_jobboard_job_offers`、`fastwork_jobboard_quota`、`fastwork_jobboard_tags`、`fastwork_jobboard_bid_schema`、`fastwork_jobboard_bid`、`fastwork_jobboard_my_bids`、`fastwork_jobboard_bid_withdraw` |
| 奖励 | `fastwork_rewards_points`、`fastwork_rewards_missions`、`fastwork_rewards_claim`、`fastwork_rewards_history`、`fastwork_rewards_catalog`、`fastwork_rewards_redeem` |
| 在线状态 | `fastwork_presence_ping` |
| 其他 | `fastwork_api_call` |
代理使用说明：
- `fastwork_chat_send`、`fastwork_chat_send_image`、`fastwork_chat_send_file` 和 `fastwork_chat_events` 需要实时套接字，除非传递 `--realtime=false`，否则实时套接字会运行。
- 附件工具接受 `file_path` 或 `content_base64`；上传存储文件，消息在同一调用中发布。
- `fastwork_quotation_schema` 文档化了提案负载；在 `fastwork_quotation_create` 之前阅读它。
- `fastwork_chat_events` 排空了最后 500 个事件的缓冲区；传递 `wait_seconds` 以阻塞直到有事件到达。
- `fastwork_service_delete` 在没有 `confirm: true` 的情况下拒绝运行。
- `fastwork_service_upload_media` 接受 `file_path` 或 `content_base64`。
## 实时聊天
聊天运行在 Phoenix 通道上：`wss://chat-api.fastwork.id/socket/websocket?vsn=2.0.0&token=<accessToken>`，主题 `user:<userId>`。发送是 `send_message` 推；服务器推 `new_message_received`、`message_updated`、`room_updated`、`read_receive_updated`、`unread_messages_count_updated` 和 `order_updated`。`fastworks watch` 以 JSON 行打印这些事件，可以将每个事件转发到 Webhook。
附件、工作提交、报价和买家评论通过聊天 Web 应用程序后端（`chat.fastwork.id/api`）进行，该后端使用 Cookie 身份验证和同源 `Origin` 头。详细信息和负载形状：[docs/chat-and-orders.md](docs/chat-and-orders.md)。
## 更改您帐户的操作
这些操作会写入实时 Fastwork 账户。CLI 要求明确的标志，MCP 工具在操作不可撤销时需要确认。
| 操作 | 影响 | 保护 |
| --- | --- | --- |
| `chat send` / `fastwork_chat_send*` | 买家立即看到消息或附件 | 无，需像发送真实回复一样处理 |
| `order submit-work` / `fastwork_order_submit_work` | 发送可交付成果并通知买家审批 | 无 |
| `order quotation create` / `fastwork_quotation_create` | 在买家的聊天中发布带价的提案 | 无 |
| `order quotation cancel` / `fastwork_quotation_cancel` | 撤回待付款的提案 | 仅在付款前 |
| `order review` / `fastwork_order_review_buyer` | 发布您对买家的评分 | 单向 |
| `service submit` / `fastwork_service_submit` | 服务进入审查，通常立即发布 | 无 |
| `service visible --show=false` | 从搜索中隐藏服务 | 可逆 |
| `service delete` / `fastwork_service_delete` | 永久删除服务 | `--yes` 标志 / `confirm: true` |
| `service update` 在实时服务上 | 作为待审批的修订落地 | 无 |
| `jobboard bid` / `fastwork_jobboard_bid` | 向工作所有者发送真实的提案，并从配额中使用一个竞标 | `--dry-run` / `dry_run` 预览负载 |
| `jobboard withdraw` / `fastwork_jobboard_bid_withdraw` | 删除您的竞标，工作所有者会丢失提案 | `--yes` / `confirm: true` |
| `rewards claim` / `fastwork_rewards_claim` | 声明任务积分；未完成的任务会无害地失败 | 无 |
| `rewards redeem` / `fastwork_rewards_redeem` | 消费积分，无退款 | `--yes` / `confirm: true` |
| `presence` | 记录每日在线签到 | 无 |
## 环境
| 变量 | 用途 |
| --- | --- |
| `FASTWORK_EMAIL`、`FASTWORK_PASSWORD` | 登录凭证 |
| `FASTWORKS_PROFILE` | 默认配置文件名称 |
| `FASTWORKS_SESSION_DIR` | 会话目录（默认为 `~/.config/fastworks`） |
| `FASTWORK_API_BASE`、`FASTWORK_SELLER_BASE`、`FASTWORK_AUTH_BASE` | 端点覆盖 |
| `FASTWORK_CHAT_API_BASE`、`FASTWORK_CHAT_SOCKET_BASE`、`FASTWORK_CHAT_BFF_BASE` | 聊天端点覆盖 |
| `FASTWORK_JOBBOARD_API_BASE`、`FASTWORK_JOBBOARD_ORIGIN` | 职位板端点覆盖 |
| `FASTWORK_REWARDS_API_BASE`、`FASTWORK_REWARDS_ORIGIN` | 奖励端点覆盖 |
| `FASTWORK_CLIENT_ID`、`FASTWORK_CALLBACK_URL` | OAuth 样式的客户端设置 |
| `FASTWORK_USER_AGENT`、`FASTWORK_LANGUAGE`、`FASTWORK_LOCALE` | 请求标识 |
| `FASTWORK_TIMEOUT` | HTTP 超时，例如 `45s` |
## 测试
```bash
make check # gofmt 检查，go vet，go test ./...
go test -race ./...
```
测试运行在 `httptest` 伪造品上，包括 Phoenix WebSocket 存根，因此不需要实时 Fastwork 账户。
## CI 和发布
| 工作流 | 触发 | 它做了什么 |
| --- | --- | --- |
| `ci.yml` | 推送到 `main` / `feat/**` / `fix/**`，PR 到 `main` | gofmt 检查，`go vet`，`go test -race`，构建两个二进制文件，`工具/列表` 烟雾测试 |
| `autotag.yml` | 推送到 `main`，手动 | 从上一个标签读取 Conventional Commits，选取下一个 semver，推送标签，然后调用发布工作流 |
| `release.yml` | 标签 `v*`，手动，或由 `autotag.yml` 调用 | 跨编译五个目标，包装存档与 README 和文档，写入 `checksums.txt`，发布 GitHub 发布 |
用于 `autotag.yml` 的标签规则：
| 提交主题 | 提升 |
| --- | --- |
| `feat!: …` 或带有 `BREAKING CHANGE` 页脚 | 主要 |
| `feat: …` | 次要 |
| `fix: …`、`perf: …`、`refactor: …`、`revert: …` | 修补 |
| 只有 `chore: …`、`docs: …`、`test: …`、`ci: …` | 无发布 |
手动覆盖：运行“自动标记和发布”工作流并选择 `patch`、`minor` 或 `major`。要重新发布现有标签，请使用该标签运行“发布”，版本字符串被标记到两个二进制文件中，因此 `fastworks version` 和 `fastworks-mcp --version` 报告发布的标签。
## 布局
```
cmd/fastworks/ CLI 入口点
cmd/fastworks-mcp/ MCP 标准输入输出服务器入口点
internal/fastwork/ REST + GraphQL 客户端，身份验证，订单，产品，卖家数据
internal/chat/ 聊天 REST 客户端和 Phoenix 套接字
internal/jobboard/ 职位板浏览和竞标
internal/rewards/ 积分，任务，兑换目录
internal/session/ 会话存储，持久 Cookie Jar，JWT 解码
internal/cliapp/ CLI 命令
internal/mcpserver/ JSON-RPC/MCP 管道和工具定义
docs/ 端点和字段参考
.github/workflows/ CI，自动标记，发布
```
## 文档
- [docs/service-fields.md](docs/service-fields.md) — 每个可写的服务字段，限制，验证规则，创建到提交的顺序
- [docs/chat-and-orders.md](docs/chat-and-orders.md) — 聊天附件，工作提交，提案，买家评论
- [docs/jobboard-and-rewards.md](docs/jobboard-and-rewards.md) — 职位板浏览和竞标，奖励积分和任务
- [docs/fastwork-endpoints.md](docs/fastwork-endpoints.md) — 按主机观察到的完整端点目录
## 注意事项和限制
- Fastwork 不会发布公共 API。端点由卖家和聊天 Web 应用程序观察，可以在不通知的情况下更改。
- 会话文件保存长期令牌；将 `~/.config/fastworks` 视为 SSH 密钥目录。永远不要提交它。
- `go.work` 被故意忽略：这是一个单一模块，因此工作区文件仅用于本地开发配置。
- 提交消息遵循 Conventional Commits；发布标签由此导出。
- 订单有效载体作为原始 JSON 返回，因为形状未记录；用于开发的帐户没有活动订单来建模。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器