Skip to main content
Glama
deenesjakoruzh
mahrukh-n8n

Freedcamp MCP Server

by mahrukh-n8n
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Freedcamp MCP 服务器

这是一个封装了 Freedcamp REST API 的 Model Context Protocol 服务器。它允许任何兼容 MCP 的 LLM 客户端（如 Claude Code、Claude Desktop 等）通过自然语言管理 Freedcamp 项目、任务、用户和评论。

功能特性

  • 17 个工具：涵盖项目、任务、用户、评论和健康检查

  • HMAC-SHA1 身份验证 — API 密钥绝不会离开服务器；每次请求仅发送签名哈希

  • 名称解析 — 传入用户名、电子邮件或项目名称，而非原始数字 ID；服务器会自动通过基于 TTL 的缓存进行解析

  • 字段限制 — 使用点号表示法（id,title,comments.created_ts）仅请求所需的字段，以减小响应大小

  • 状态标签映射 — 接受如 "in progress" 这样的人类可读字符串，而非数字代码

  • 响应过滤 — 自动从响应中剥离内部 API 字段

  • 优雅关闭 — 在退出前处理完正在进行的请求

  • 重试 + 退避 — 在遇到 429 和 5xx 错误时进行指数退避重试

  • 无需构建步骤 — 通过 tsx 直接运行 TypeScript

Related MCP server: toggl-mcp

前置要求

  • Node.js >= 18

  • 拥有 API 凭据的 Freedcamp 账户（设置 → API）

安装

git clone https://github.com/mahrukh-n8n/freedcampMCP.git
cd freedcampMCP
npm install

配置

选项 A：.env 文件

cp .env.example .env
# Edit .env with your Freedcamp API key and secret

选项 B：Claude Code MCP 设置

无需 .env 文件 — 将凭据作为环境变量传入：

claude mcp add freedcamp npx tsx /path/to/freedcampMCP/scripts/mcp-server.ts \
  -e FREEDCAMP_API_KEY=your_key \
  -e FREEDCAMP_API_SECRET=your_secret

环境变量

变量

必需

默认值

描述

FREEDCAMP_API_KEY

是

—

Freedcamp API 密钥

FREEDCAMP_API_SECRET

是

—

Freedcamp API 密钥

FREEDCAMP_API_URL

否

https://freedcamp.com

基础 URL（用于自托管）

LOG_LEVEL

否

info

日志级别：debug, info, warn, error

REQUEST_TIMEOUT_MS

否

30000

HTTP 请求超时时间（毫秒）

CACHE_TTL_MS

否

60000

名称解析缓存 TTL（毫秒）

MAX_CONCURRENT_REQUESTS

否

6

最大并发 API 请求数

运行

使用 Claude Code（推荐）

在通过 claude mcp add 添加 MCP 服务器后，直接开始对话即可。Claude 会在需要时自动调用工具。

使用 MCP Inspector

npx @modelcontextprotocol/inspector npx tsx scripts/mcp-server.ts

打开浏览器 UI，您可以在其中调用每个工具并检查响应。

直接运行 (stdio)

npx tsx scripts/mcp-server.ts

服务器使用 MCP stdio 传输在 stdin/stdout 上监听。宿主进程（Claude Code、Claude Desktop）负责管理其生命周期。

工具

健康检查

工具

描述

health.check

验证 API 凭据和连接状态

项目

工具

写入

描述

project.list

列出项目（支持分页、排序、字段限制）

project.get

通过 ID 或名称获取项目

project.create

是

创建项目（名称、描述、颜色、组、成员）

project.update

是

更新项目字段（部分更新）

任务

工具

写入

描述

task.list

列出任务（支持筛选：负责人、状态、日期范围、搜索、标签）

task.get

通过 ID 获取任务（包含评论和标签详情；注入 task_url）

task.create

是

创建任务（接受状态标签、文件附件）

task.update

是

更新任务字段（部分更新、文件附件）

task.delete

是

删除任务

task.assign

是

为任务分配用户

用户

工具

写入

描述

user.list

列出用户（可选按项目筛选）

user.get

通过 ID、电子邮件或名称获取用户

user.current

获取已认证用户的个人资料

user.create

是

创建用户（电子邮件、密码、名字、OAuth）

user.update_current

是

更新已认证用户的个人资料

评论

工具

写入

描述

comment.add

是

添加评论（需要 item_id + app_id）

comment.update

是

更新评论文本

comment.delete

是

删除评论

名称解析

大多数 ID 参数接受名称、电子邮件或数字 ID。示例：

  • project_id: "Marketing" — 解析为项目的数字 ID

  • assigned_to_id: "alice@example.com" — 解析为用户的数字 ID

  • assigned_to_id: ["Alice", 42] — 接受混合列表

解析结果会使用可配置的 TTL (CACHE_TTL_MS) 进行缓存。

状态映射

任务状态同时接受数字代码和字符串标签：

代码

标签

0

not started

1

in progress

2

completed

示例：status: "in progress" 等同于 status: 1。

字段限制

所有列表和获取工具都接受带有点号路径的 fields 参数：

fields="id,title,priority,comments.created_ts"

这可以减小响应大小并使 LLM 专注于相关数据。嵌套数组会被保留 — [{created_ts: 1}] 上的 comments.created_ts 会产生 [{created_ts: 1}]，而不是扁平列表。

应用 ID 常量（用于评论）

应用

ID

tasks

2

milestones

3

discussions

5

files

6

time

8

issue_tracker

9

身份验证

服务器使用 HMAC-SHA1 身份验证。在每次请求时：

  1. 生成一个 Unix 时间戳

  2. 计算哈希：HMAC-SHA1(secret, apiKey + timestamp)

  3. 身份验证参数作为查询字符串发送：?api_key=...&timestamp=...&hash=...

密钥绝不会通过网络传输。在启动时，服务器会使用 GET /api_key/check 验证凭据。

错误代码

代码

含义

PERMISSION_DENIED

API 密钥/密钥无效或访问权限不足

NOT_FOUND

请求的资源或名称解析目标不存在

VALIDATION_ERROR

输入参数无效

CONFLICT

资源已存在

INTERNAL_ERROR

服务器错误、速率限制或网络故障

开发

# Type check
npx tsc --noEmit

# Run tests
npx vitest run

# Watch mode
npx vitest

# Run server in dev mode
npm run dev

测试

测试套件使用 Vitest 和模拟的 API 响应：

npx vitest run           # Single run
npx vitest               # Watch mode
npx vitest --coverage    # With coverage

项目结构

scripts/mcp-server.ts              Entry point
src/lib/freedcamp/
  api-client.ts                    HTTP client with HMAC auth, retry, filtering
  register-tools.ts                Wire all tools to the MCP registry
  auth/hmac.ts                     HMAC-SHA1 computation
  auth/hmac-validator.ts           Boot-time credential validation
  tools/
    health.ts                      health.check
    projects.ts                    project.list/get/create/update
    tasks.ts                       task.list/get/create/update/delete/assign
    users.ts                       user.list/get/current/create/update_current
    comments.ts                    comment.add/update/delete
  utils/
    name-resolver.ts               Name/email → ID resolution with caching
    response-filter.ts             Strip internal fields from API responses
    field-limiter.ts               Dot-notation field extraction
    date-utils.ts                  Date validation and formatting
    resolution-cache.ts            TTL-based LRU cache
    logger.ts                      Structured logging with verbose mode
    validation.ts                  Input validation helpers
src/modules/mcp/
  registry/tool-registry.ts        MCP tool registry
  services/create-mcp-server.ts    MCP server factory
  services/stdio-transport.ts      Stdio transport
  types.ts                         MCP result types
  utils/serialize.ts               Result envelope helpers (dataResult, commitResult, etc.)

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers