FreeAgent MCP 服务器

一个 Claude MCP (模型上下文协议) 服务器，用于管理 FreeAgent 时间记录和计时器。此服务器允许 Claude 与您的 FreeAgent 帐户交互，以跟踪时间、管理计时器和处理时间记录操作。

功能

• 列出和筛选带有嵌套数据的时间记录
• 创建新的时间记录
• 更新现有的时间记录
• 启动和停止计时器
• 删除时间记录
• 自动 OAuth 令牌刷新
• 完善的错误处理
• Docker 支持

前提条件

• Node.js 18+ (用于直接 Node.js 使用)
• Docker & Docker Compose (用于容器化使用)
• 具有 API 访问权限的 FreeAgent 帐户
• 来自 FreeAgent 开发者仪表板 的 OAuth 凭据

安装

选项 1：直接 Node.js 安装

1. 克隆存储库：

git clone https://github.com/yourusername/freeagent-mcp.git
cd freeagent-mcp

2. 安装依赖项：

npm install

3. 获取您的 OAuth 令牌：

# 设置您的 FreeAgent 凭据
export FREEAGENT_CLIENT_ID="your_client_id"
export FREEAGENT_CLIENT_SECRET="your_client_secret"

# 运行 OAuth 设置脚本
node scripts/get-oauth-tokens.js

选项 2：Docker 安装

1. 克隆存储库：

git clone https://github.com/yourusername/freeagent-mcp.git
cd freeagent-mcp

2. 创建您的环境变量文件：

cp .env.example .env
# 使用您的 FreeAgent 凭据编辑 .env

3. 构建 Docker 镜像：

docker build -t freeagent-mcp .

配置

将服务器添加到您的 MCP 设置（通常在 %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 中）：

对于 Node.js 安装：

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["path/to/freeagent-mcp/build/index.js"],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_ACCESS_TOKEN": "your_access_token",
        "FREEAGENT_REFRESH_TOKEN": "your_refresh_token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

对于 Docker 安装：

{
  "mcpServers": {
    "freeagent": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "FREEAGENT_CLIENT_ID",
        "-e", "FREEAGENT_CLIENT_SECRET",
        "-e", "FREEAGENT_ACCESS_TOKEN",
        "-e", "FREEAGENT_REFRESH_TOKEN",
        "freeagent-mcp"
      ],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_ACCESS_TOKEN": "your_access_token",
        "FREEAGENT_REFRESH_TOKEN": "your_refresh_token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

用法

配置完成后，Claude 可以使用以下工具：

列出时间记录

{
  "from_date": "2024-01-01",      // 开始日期 (YYYY-MM-DD)
  "to_date": "2024-03-04",        // 结束日期 (YYYY-MM-DD)
  "updated_since": "2024-03-04T12:00:00Z",  // ISO 日期时间
  "view": "all",                  // "all", "unbilled", 或 "running"
  "user": "https://api.freeagent.com/v2/users/123",
  "task": "https://api.freeagent.com/v2/tasks/456",
  "project": "https://api.freeagent.com/v2/projects/789",
  "nested": true                  // 包括嵌套资源
}

创建时间记录

{
  "task": "https://api.freeagent.com/v2/tasks/123",
  "user": "https://api.freeagent.com/v2/users/456",
  "project": "https://api.freeagent.com/v2/projects/789",
  "dated_on": "2024-03-04",
  "hours": "1.5",
  "comment": "可选评论"
}

计时器控制

// 启动计时器
{
  "id": "123"
}

// 停止计时器
{
  "id": "123"
}

开发

Node.js 开发

# 构建项目
npm run build

# 监听更改
npm run watch

# 运行测试 (如果已实现)
npm test

Docker 开发

# 构建 Docker 镜像
docker build -t freeagent-mcp .

贡献

1. Fork 存储库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -am 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

鸣谢

• FreeAgent 提供的出色 API 文档
• Claude 团队提供的 MCP SDK