JinDaGe - FreeAgent MCP Details

article

README

🚀 FreeAgent MCP 服务

FreeAgent MCP 服务是一个 Claude MCP（模型上下文协议）服务器，用于管理 FreeAgent 工时记录和计时器。该服务器能让 Claude 与您的 FreeAgent 账户进行交互，实现时间跟踪、计时器管理以及工时记录操作等功能。

🚀 快速开始

FreeAgent MCP 服务可助力您高效管理 FreeAgent 工时记录和计时器。以下为您详细介绍使用前的准备工作、安装步骤、配置方法以及基本使用示例。

✨ 主要特性

可列出和过滤带嵌套数据的工时记录。
支持创建新的工时记录。
能够更新现有工时记录。
可启动和停止计时器。
允许删除工时记录。
具备自动刷新访问令牌的功能。
拥有全面的错误处理机制。
支持 Docker 部署。

📦 安装指南

选项 1：直接 Node.js 安装

克隆仓库：

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

安装依赖项：

npm install

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

克隆仓库：

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

构建 Docker 映像：

docker build -t freeagent-mcp .

运行容器：

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 .

贡献

叉克仓库。
创建功能分支 (git checkout -b feature/amazing-feature)。
提交更改 (git commit -am 'Add some amazing feature')。
推送到分支 (git push origin feature/amazing-feature)。
打开 Pull Request。

📄 许可证

此项目在 MIT 许可证下发布——查看 LICENSE 文件以获取详细信息。

👏 致谢

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

FreeAgent