FreeAgent MCP 服务器

一个用于管理 FreeAgent 时间条目和计时器的 Claude MCP（Model Context Protocol）服务器。此服务器允许 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

1. 安装依赖项：

npm install

1. 获取您的 OAuth 令牌：

# Set your FreeAgent credentials
export FREEAGENT_CLIENT_ID="your_client_id"
export FREEAGENT_CLIENT_SECRET="your_client_secret"

# Run the OAuth setup script
node scripts/get-oauth-tokens.js

选项 2：Docker 安装

1. 克隆仓库：

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

1. 创建环境文件：

cp .env.example .env
# Edit .env with your FreeAgent credentials

1. 构建 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",      // Start date (YYYY-MM-DD)
  "to_date": "2024-03-04",        // End date (YYYY-MM-DD)
  "updated_since": "2024-03-04T12:00:00Z",  // ISO datetime
  "view": "all",                  // "all", "unbilled", or "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                  // Include nested resources
}

创建时间条目

{
  "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": "Optional comment"
}

计时器控制

// Start timer
{
  "id": "123"
}

// Stop timer
{
  "id": "123"
}

开发

Node.js 开发

# Build the project
npm run build

# Watch for changes
npm run watch

# Run tests (when implemented)
npm test

Docker 开发

# Build the Docker image
docker build -t freeagent-mcp .

贡献

1. 分叉仓库
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