Mellow&Scout MCP服务器
远程 模型上下文协议（MCP） 服务器 柔和 和 AI侦察员，使用Mellow OAuth部署在Cloudflare Workers上。
Mellow帮助公司在全球范围内雇佣、管理和支付承包商——处理合同、合规、入职和国际支付。通过此服务器暴露了两种产品：
- 记录承包商（CoR） --雇佣承包商，运行任务生命周期（草案→ 发布→ 接受→ 付款），收集结算文件。
- AI侦察员 --寻找候选人，人工智能生成职位描述，对外共享，管理应用程序和私人承包商池。
代理在安装时获得什么
当任何MCP客户端（Claude Desktop、Cursor、MCP Inspector、ChatGPT）连接时，服务器返回三件事：
- 工具 --76个可调用工具，每个工具都有一个丰富的描述，阐明了先决条件、错误语义和已知的错误警告。
instructions（~6KB初级）——大多数客户端会自动将其作为系统提示注入。涵盖身份、两步接受和支付流程、ID语义(workerId≡freelancerId)，任务状态机，多公司通过X-Company-Id，要避免的顶级陷阱，以及指向以下资源的指针。- 资源 --代理可以通过URI读取三个按需参考文档：
- mellow://domain --完整的领域指南（参与者、产品、状态机、前提条件、决策树） - mellow://workflows --12个端到端的食谱（入职、接受和支付、童子军雇佣、多币种、批量进口） - mellow://anti-patterns --常见的代理错误，有好/坏的例子
底漆经过精心设计，以便阅读它的代理人 之前 第一个工具调用已经知道不明显的规则，例如 acceptTask 不付款（单独 payForTask 步骤是必需的），并且 declineTask 这不是一个通用的取消。
建筑
服务器充当OAuth代理：
- OAuth服务器 MCP客户（Claude、Cursor等）
- OAuth客户端 转到Mellow的身份验证服务(
wlcm.mellow.io)
这两个产品共享相同的身份验证流和访问令牌。服务器创建两个API客户端，其中一个用于 my.mellow.io （CoR）和一个用于 aiscout-api.mellow.io （Scout）——并从两者中注册工具。A每次会议 X-Company-Id 头部（由驱动 Props.activeCompanyId)处理多公司用户。
堆栈
- Cloudflare员工 +耐用物品
workers-oauth-provider适用于OAuth 2.1@modelcontextprotocol/sdk用于MCP协议- 荣誉 对于OAuth回调处理程序
- 佐德 用于工具输入验证
工具（共76个）
梅洛（CoR）
| 模块 | 工具 | 说明 |
|---|---|---|
| 任务（15） | listTasks, getTask, createTask, publishDraftTask, changeTaskStatus, changeDeadline, acceptTask, payForTask, declineTask, resumeTask, getTaskMessages, addTaskMessage, addTaskFiles, checkTaskRequirements, getAllowedCurrencies | 任务生命周期。接受和支付分为两步： acceptTask → payForTask. |
| 任务组（4） | listTaskGroups, createTaskGroup, renameTaskGroup, deleteTaskGroup | 文档导出的项目/专业分组。 |
| 自由职业者（9） | listFreelancers, getFreelancer, inviteFreelancer, findFreelancerByEmail, findFreelancerByPhone, editFreelancer, editFreelancerProfile, removeFreelancer, getFreelancerTaxInfo | 根据公司承包商管理。KYC/联系人变更/税务状态由自由职业者在自己的UI中处理，而不是通过此MCP。 |
| 交易记录（1） | listTransactions | 公司财务分类账（充值、借记、更正、税款）。 |
| 公司（3） | listCompanies, switchCompany, getCompanyBalance | 多公司支持。更喜欢 X-Company-Id 根据请求 switchCompany 对于平行会议。 |
| 文件（2） | listDocuments, downloadDocument | 期末单据（发票类型6，期间报告类型7）。 |
| 简介（1） | getUserProfile | 当前用户信息。 |
| 参考文献（9） | getCurrencies, getExchangeRate, getTaxStatuses, getServices, getTaskAttributes, getAcceptanceDocuments, getTaxDocumentTypes, getSpecializations, getCountries | 查找目录值。 |
| Webhooks（3） | getWebhook, createOrUpdateWebhook, deleteWebhook | Webhook配置。 后端路由当前为404（BUG-6） --为forward compat注册的工具。 |
| ChatGPT网桥（2） | search, fetch | 跨任务和自由职业者的跨实体搜索。 |
AI侦察员(scout_ 前缀）
| 模块 | 工具 | 说明 |
|---|---|---|
| 职位（7） | scout_listPositions, scout_getPosition, scout_createPosition, scout_updatePosition, scout_closePosition, scout_openPosition, scout_sharePosition | 承包商要求生命周期。两个州： active ↔ closed. |
| 应用程序（5） | scout_listApplications, scout_listPositionApplications, scout_getApplication, scout_changeApplicationStatus, scout_inviteApplicant | 候选管道。后端没有转换保护——代理必须强制执行合理的状态流。 scout_inviteApplicant 这是一封电子邮件，而不是CoR约定。 |
| 人工智能任务（2） | scout_generatePosition, scout_getGeneratePositionTask | 异步AI生成职位描述。 |
| 促销帖子（2） | scout_createPromoPosts, scout_getPromoPosts | 异步社交媒体帖子生成以共享职位。 |
| 游泳池（7） | scout_getPool, scout_listPoolFreelancers, scout_getPoolFreelancer, scout_createPoolFreelancer, scout_editPoolFreelancer, scout_deletePoolFreelancer, scout_deletePoolFreelancersBatch | 每家公司的私人承包商数据库。 scout_deletePoolFreelancersBatch 没有后端大小上限——请与用户确认大批量。 |
| 附件/公司/查询（4） | scout_getAttachmentMetadata, scout_listCompanies, scout_getCountries, scout_getShortLink | 杂项侦察员参考/元数据。 |
对于完整的每工具语义，请获取 mellow://workflows 和 mellow://anti-patterns 运行时的资源，或读取 docs/DOMAIN.md 和 docs/WORKFLOWS.md 在设计阶段。
文档
所有文档 docs/ 面向代理——三个也捆绑到worker中，作为MCP资源：
docs/DOMAIN.md--领域指南：产品、参与者、ID语义、多公司、状态机、前提条件、决策树。担任mellow://domain.docs/WORKFLOWS.md--12个端到端的食谱，带有具体的工具序列和错误处理。担任mellow://workflows.docs/ANTI_PATTERNS.md--常见代理错误目录（坏→ Why → 很好）。担任mellow://anti-patterns.docs/BACKEND_TICKETS.md--影响MCP工具的开放后端问题的实时状态。仅面向工程（不捆绑）。
CLAUDE.md 在repo根目录下是Claude Code在编辑此存储库时使用的项目指令文件。
设置
先决条件
- Node.js 20+
- 启用Workers的Cloudflare帐户
- Mellow OAuth应用程序凭据
安装
npm install秘密
通过牧马人设置（一次性）：
npx wrangler secret put MELLOW_CLIENT_ID
npx wrangler secret put MELLOW_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY # openssl rand -hex 32环境变量
非秘密配置存在 wrangler.jsonc:
| 变量 | 值 |
|---|---|
MELLOW_API_BASE_URL | https://my.mellow.io/api |
MELLOW_BASE_URL | https://wlcm.mellow.io |
SCOUT_API_BASE_URL | https://aiscout-api.mellow.io/api |
KV命名空间
OAuth KV命名空间已在中配置 wrangler.jsonc.如果设置新的部署：
npx wrangler kv namespace create "OAUTH_KV"更新 id 在 wrangler.jsonc 使用返回的命名空间ID。
发展
npx wrangler dev服务器启动时间 http://localhost:8788.创建一个 .dev.vars 本地OAuth凭据文件：
MELLOW_CLIENT_ID=your_dev_client_id
MELLOW_CLIENT_SECRET=your_dev_client_secret
COOKIE_ENCRYPTION_KEY=your_random_hex_string类型检查
npm run type-check 是主要的正确性门（未配置测试框架）。
重新生成Cloudflare类型
修改后 wrangler.jsonc 绑定或变量：
npm run cf-typegen注意：秘密绑定是 *不* 捡到的 wrangler types。它们在中手动声明 src/types/env-secrets.d.ts 以保持源代码的键入。
MCP检验员测试
npx @modelcontextprotocol/inspector@latest进入 http://localhost:8788/sse 并连接。在OAuth流程之后，您应该看到：
- 试剂底漆在 服务器信息/说明 视图
- 76种工具 工具
- 列出了3个资源 资源 (
mellow://domain,mellow://workflows,mellow://anti-patterns)
部署
npx wrangler deploy连接MCP客户端
克劳德桌面/克劳德代码
{
"mcpServers": {
"mellow": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.it-dep-271.workers.dev/sse"
]
}
}
}光标
类型： 命令，命令： npx mcp-remote https://mcp.it-dep-271.workers.dev/sse
ChatGPT（通过mcp远程）
与Claude Code相同的模式——客户端连接，完成OAuth，然后可以访问工具、指令和资源。
添加工具
- 在适当的位置填写注册信息
src/tools/.ts.使用server.tool(name, description, zodSchema, handler)并让MellowClient通过处理HTTPclient.get/post/put/patch/del. - 如果描述教会了代理一些关于状态、错误或已知错误的不明显的东西，那么就明确地说出来。代理系统提示和工具描述是主要合同。
- 接通电源
src/index.ts仅在创建时需要 *新* 模块文件。 - 跑
npm run type-check那么npx wrangler deploy --dry-run进行构建健全性检查。
有关对代理表面（底漆、资源）的更广泛编辑，请参见 src/agent-primer.ts 和那个 registerResource() 来电 src/index.ts.