Freeagent

🚀 FreeAgent MCP 服務

FreeAgent MCP 服務是一個基於 Claude MCP（模型上下文協議）的服務器，主要用於管理 FreeAgent 的工時記錄和計時器。藉助該服務器，Claude 能夠與您的 FreeAgent 賬戶進行交互，實現時間跟蹤、計時器管理以及工時記錄操作等功能。

🚀 快速開始

FreeAgent MCP 服務允許您通過 Claude MCP 與 FreeAgent 賬戶交互，實現工時記錄和計時器的管理。以下是使用該服務的基本步驟：

1. 完成安裝（可選擇直接使用 Node.js 或通過 Docker 安裝）。
2. 進行必要的配置，設置環境變量。
3. 依據需求調用相應的 API 進行工時記錄的管理和計時器的控制。

✨ 主要特性

• 工時記錄管理：支持列出和過濾帶嵌套數據的工時記錄，還能創建、更新和刪除工時記錄。
• 計時器控制：可以啟動和停止計時器，方便準確記錄工作時間。
• 自動刷新：自動刷新訪問令牌，確保服務的持續穩定運行。
• 錯誤處理：具備全面的錯誤處理機制，保障系統的健壯性。
• 容器化支持：提供 Docker 支持，方便部署和管理。

📦 安裝指南

選項 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。