Fergus MCP服务器
A. 模型上下文协议（MCP） 与Fergus API集成的服务器，使Claude等人工智能助手能够与Ferguss的工作管理平台进行交互。
特性
- 🔐 安全身份验证（PAT用于本地，OAuth 2.0用于远程）
- 🌐 双重运输支持： 标准 （本地CLI）和 超文本传输协议 （远程网络）
- 📋 26多种用于工作、客户、报价、网站、时间条目和用户的工具
- 🛠️ 创建、读取和更新Fergus资源
- 🔄 Fergus API实时数据同步
- 💬 常见工作流的内置提示
运输方式
此服务器支持两种传输模式：
- Stdio（本地）：AI客户端（Claude Code、Claude Desktop）将MCP服务器作为您计算机上的本地子进程生成。通信通过stdin/stdout管道进行。因为客户端和服务器在相同的用户帐户下运行， 不需要MCP级别的身份验证 -您只需提供Fergus API令牌，服务器就可以代表您调用Fergus API。
- HTTP（远程）：MCP服务器在远程主机上运行，客户端通过网络连接。因为服务器暴露在互联网上， OAuth 2.0用于对客户端进行身份验证 在他们能够访问Fergus资源之前。经过身份验证后，服务器通过OAuth会话管理Fergus API访问。
入门指南
先决条件
- （v18+）
- 多伦多证券交易所 全局安装：
pnpm add -g tsx设置
- 克隆此存储库
- 安装依赖项：
pnpm install- 构建项目：
pnpm run build可选配置
--base-url：覆盖默认的Fergus API基础URLFERGUS_BASE_URL：基本URL的环境变量
配置AI客户端
本地模式（标准）
A. Fergus个人访问令牌（PAT） 是必需的。从您的Fergus帐户设置中获取。此令牌不用于MCP身份验证，它允许服务器代表您调用Fergus API。
克劳德代码
claude mcp add fergus-mcp -- tsx path/to/fergus-mcp/src/index.ts --api-token YOUR_API_TOKEN克劳德桌面
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"fergus": {
"command": "tsx",
"args": ["path/to/fergus-mcp/src/index.ts", "--api-token", "YOUR_API_TOKEN"]
}
}
}其他AI客户端（通用）
将此配置添加到客户端的MCP连接器设置中：
{
"command": "tsx",
"args": ["path/to/fergus-mcp/src/index.ts", "--api-token", "YOUR_API_TOKEN"]
}您还可以通过以下方式提供令牌 .env 文件改为：
FERGUS_API_TOKEN=your_fergus_api_token_here远程模式（HTTP）
MCP服务器必须托管并配置为 OAuth 2.0凭据 因此客户端可以进行身份验证。在中配置这些 .env 在您的服务器上：
# Required OAuth Configuration
COGNITO_USER_POOL_ID=us-east-1-xxxxx
COGNITO_CLIENT_ID=your_client_id
COGNITO_CLIENT_SECRET=your_client_secret
COGNITO_REGION=us-east-1
COGNITO_DOMAIN=auth.fergus.com
OAUTH_REDIRECT_URI=https://your-domain.com/oauth/callback
# Server Configuration
HTTP_PORT=3100
PUBLIC_URL=https://your-domain.com看 .env.example 了解完整的配置选项。
在开始之前：
- 您可以托管此MCP服务器的自己版本（请参阅 部署).
- 如果你只是想快速尝试，我们在以下位置维护一个共享测试实例
https://fergus-mcp-server.onrender.com/mcp，但我们不保证它始终可用。
克劳德网络和克劳德桌面（远程连接器）
- 启动克劳德桌面（v1.8.2+）或访问 claude.ai，打开 设置→ 模型上下文.
- 启用 远程连接器，单击 添加远程服务器，并输入托管服务器的域（无路径或协议）。
- 在系统提示时批准连接器。Claude验证域，自动发现MCP元数据，并打开Fergus部署提供的OAuth窗口。
- 完成Fergus OAuth登录。Claude存储会话，连接器出现在模型上下文面板中。对每个需要访问权限的团队成员重复这些步骤。
ChatGPT自定义连接器
- 在ChatGPT（web应用程序）中，打开 设置→ 连接器→ 远程MCP服务器.
- 选择 添加远程服务器，提供托管Fergus MCP服务器的公共域，并确认。
- ChatGPT获取服务器清单；批准信任域的提示并遵循Fergus OAuth流程。重定向完成后，连接器将显示在 我的连接器 为了以后的聊天。
光标IDE（v0.4+）
- 在光标中，打开 设置→ MCP 并切换 启用远程MCP.
- 点击 添加远程MCP，为您的Fergus MCP部署提供公共域，并确认。Cursor验证已知的端点，并提示您通过OAuth登录。
- 握手结束后，选择
fergus只要你想让Cursor调用Fergus工具，就可以在聊天侧边栏中使用连接器。
提示：如果您轮换OAuth凭据或更改 PUBLIC_URL，重新运行这些客户端设置步骤，以便每个客户端刷新其元数据和令牌。可用工具
此服务器提供26多种按资源类型组织的工具：
工作（5个工具）
get-job：按ID获取特定作业的详细信息list-jobs：列出所有具有筛选和排序功能的作业create-job：创建新作业（草稿或最终确定）update-job：更新现有作业草稿finalize-job：将草稿作业转换为活动状态
报价（7个工具）
get-quote：获取基本报价信息get-quote-detail：获取包含章节和行项目的综合报价list-quotes：列出带筛选的报价create-quote：使用章节和行项目创建报价update-quote：更新报价草稿部分（按报价ID）update-quote-version：更新报价草案部分（按版本号）
客户（3个工具）
get-customer：获取客户详细信息list-customers：通过搜索列出客户create-customer：添加新客户update-customer：修改客户详细信息
网站（3个工具）
get-site：获取站点详细信息list-sites：列出具有筛选功能的网站create-site：添加新站点update-site：修改站点详细信息
用户（3个工具）
get-user：获取用户/团队成员详细信息list-users：列出具有筛选功能的用户update-user：更新用户详细信息
时间条目（2个工具）
get-time-entry：获取时间输入详细信息list-time-entries：列出具有筛选功能的时间条目
内置提示（3）
job-creation-assistant：创建工作的指导工作流程quote-generator：帮助创建综合报价weekly-report：生成作业状态摘要
用法示例
连接后，您可以问Claude：
- “显示Fergus的所有活动工作”
- “为工作#12345创建报价”
- “列出奥克兰的所有客户”
- “更新站点#456的地址”
- “显示本周的时间条目”
- “为ABC公司在总部创造一个新工作”
发展
项目结构
fergus-mcp/
├── src/
│ ├── index.ts # Main server entry point
│ ├── config.ts # Configuration management
│ ├── fergus-client.ts # Fergus API client wrapper
│ ├── resources/ # MCP resource handlers
│ └── tools/ # MCP tool handlers
├── package.json
├── tsconfig.json
└── README.md脚本
pnpm run build-构建项目pnpm run dev:http-在开发模式下运行HTTP服务器pnpm run docker:build-构建Docker镜像pnpm start-stdio的入口点pnpm start:http-运行内置的HTTP服务器
部署
快速部署以渲染（推荐）
此服务器已准备好部署到 渲染 使用Redis会话存储：
- 分叉或克隆 将此存储库添加到您的GitHub帐户
- 创建新蓝图 在渲染和连接存储库上
- 配置OAuth凭据 在渲染仪表板中（请参见 部署.md)
- 部署！ 渲染将自动设置：
- Node.js web服务 - 用于会话的Redis实例 - SSL证书 - 内部网络
看 部署.md 获取完整的分步说明。
其他托管服务提供商
服务器还可以部署到：
- Cloudflare员工：使用持久对象进行会话存储
- 维塞尔：通过Vercel KV配置Redis
- 铁路：与Render类似，使用
render.yaml - AWS/GCP/Azure：使用托管Redis作为容器化应用程序部署
看 .env.example 对于所需的环境变量。
安全
标准模式（本地）
- MCP服务器作为本地子进程运行——没有网络暴露，不需要MCP级别的身份验证
- Fergus API令牌作为配置值传递（不用于MCP验证，但服务器可以调用Fergus API）
- 永远不要将您的个人访问令牌提交给版本控制
- 使用环境变量或CLI参数进行配置
HTTP模式（远程）
- OAuth 2.0和PKCE在授予访问权限之前对MCP服务器的客户端进行身份验证
- 存储在内存中的令牌（对于多实例部署，可选Redis）
- 生产中需要HTTPS
- CORS和DNS重新绑定保护已启用
- 基于会话的令牌管理，具有自动刷新功能
- 没有存储或传输给第三方的数据
许可证
麻省理工学院
贡献
欢迎投稿！请打开问题或提交拉取请求。
支持
对于问题和疑问：
- GitHub问题： 创建问题
- Fergus API文件： https://api.fergus.com/docs