FreeAgent MCP 服务器

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

特征

列出并过滤带有嵌套数据的时间表
创建新的时间表
更新现有时间表
启动和停止计时器
删除时间表
自动 OAuth 令牌刷新
全面的错误处理
Docker 支持

先决条件

Node.js 18+（可直接使用 Node.js）
Docker 和 Docker Compose（用于容器化使用）
具有 API 访问权限的 FreeAgent 帐户
来自FreeAgent 开发者仪表板的 OAuth 凭证

安装

选项 1：直接安装 Node.js

克隆存储库：

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

安装依赖项：

npm install

获取您的 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 安装

克隆存储库：

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

创建您的环境文件：

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

构建 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 .

贡献

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
提交您的更改（ git commit -am 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

执照

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

致谢

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

FreeAgent MCP Server

Integrations