FreeAgent MCP 服务

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

功能

• 列出和过滤带嵌套数据的工时记录
• 创建新的工时记录
• 更新现有工时记录
• 启动和停止计时器
• 删除工时记录
• 自动刷新访问令牌
• 全面错误处理
• 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"

# 访问令牌
curl -X POST "https://oauth2api.freeagent.com/v1/oauth/token" \
     -u "$FREEAGENT_CLIENT_ID:$FREEAGENT_CLIENT_SECRET" \
     -d "grant_type=client_credentials&scope=full Accounting"

选项 2：使用 Docker 安装

1. 克隆仓库：

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

2. 构建 Docker 映像：

docker build -t freeagent-mcp .

3. 运行容器：

docker run -p 3000:3000 --env-file .env freeagent-mcp

配置

环境变量

创建一个 .env 文件，并添加以下内容：

FREEAGENT_CLIENT_ID=your_client_id
FREEAGENT_CLIENT_SECRET=your_client_secret
PORT=3000

Docker 环境变量

在 docker-compose.yml 中配置环境变量：

version: '3'
services:
  freeagent-mcp:
    image: freeagent-mcp
    ports:
      - "3000:3000"
    environment:
      - FREEAGENT_CLIENT_ID=your_client_id
      - FREEAGENT_CLIENT_SECRET=your_client_secret

使用

列出工时记录

curl http://localhost:3000/api/timeslips

创建工时记录

curl -X POST "http://localhost:3000/api/timeslips" \
     -H "Content-Type: application/json" \
     -d '{"description":"项目会议","duration":60}'

更新工时记录

curl -X PUT "http://localhost:3000/api/timeslips/123" \
     -H "Content-Type: application/json" \
     -d '{"description":"详细项目计划","duration":90}'

删除工时记录

curl -X DELETE "http://localhost:3000/api/timeslips/123"

控制计时器

启动计时器

curl -X POST "http://localhost:3000/api/timers/123/start"

停止计时器

curl -X POST "http://localhost:3000/api/timers/123/stop"

开发

Node.js 开发

# 构建项目
npm run build

# 监视更改
npm run watch

# 运行测试（当实现时）
npm test

Docker 开发

# 构建 Docker 映像
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