Advocu MCP Server

🚀 活動報告MCP服務器

本項目助力谷歌開發者專家（GDEs）通過人工智能驅動的對話界面輕鬆報告他們的活動。通過將Advocu API與模型上下文協議（MCP）集成，GDEs現在可以直接通過人工智能聊天模型或命令行工具提交他們的內容創作、演講活動、研討會、指導課程和其他活動。這簡化了報告流程，使其更直觀、更易操作，同時保持了GDE計劃所需的詳細跟蹤。

這是一個用於向Advocu GDE API報告活動的模型上下文協議（MCP）服務器。

🚀 快速開始

✨ 主要特性

• 藉助人工智能驅動的對話界面，方便谷歌開發者專家（GDEs）報告活動。
• 集成Advocu API與模型上下文協議（MCP），支持通過多種方式提交活動。
• 簡化報告流程，提高操作的直觀性和可訪問性。

📦 安裝指南

使用NPM

npm install -g advocu-mcp-server

使用npx（推薦：無需安裝）

npx advocu-mcp-server

🔧 配置步驟

前提條件

• Node.js 18+
• Advocu GDE API訪問令牌

步驟1：配置Claude Desktop

編輯Claude Desktop配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

選項A：使用全局安裝

{
  "mcpServers": {
    "activity-reporting": {
      "command": "advocu-mcp-server",
      "env": {
        "ADVOCU_ACCESS_TOKEN": "your_advocu_token_here"
      }
    }
  }
}

選項B：使用npx

{
  "mcpServers": {
    "activity-reporting": {
      "command": "npx",
      "args": ["-y", "advocu-mcp-server"],
      "env": {
        "ADVOCU_ACCESS_TOKEN": "your_advocu_token_here"
      }
    }
  }
}

步驟2：重啟Claude Desktop

關閉並重新打開Claude Desktop以加載新配置。

🔧 本地開發設置（可選）

如果你想為項目做貢獻或修改服務器：

git clone https://github.com/carlosazaustre/advocu-mcp-server.git
cd advocu-mcp-server
npm install
npm run build

然後使用本地路徑配置Claude Desktop：

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/absolute/path/to/advocu-mcp-server/dist/index.js"],
      "env": {
        "ADVOCU_ACCESS_TOKEN": "your_advocu_token_here"
      }
    }
  }
}

💻 使用示例

基礎用法

在Claude中，你可以使用如下命令：

"Submit a content creation activity for my blog post about React hooks published on Medium"
"Create a public speaking draft for my presentation at ReactConf 2024"
"Report a mentoring session I had with 3 junior developers about TypeScript"

📚 詳細文檔

有關所有可用端點、參數和數據格式的詳細信息，請參閱 API文檔。

🔧 技術細節

開發模式

npm run dev

構建

npm run build

代碼檢查和格式化

npm run lint
npm run format

🔧 速率限制

API每分鐘限制30個請求。服務器會自動處理429錯誤。

🔧 項目結構

advocu-mcp-server/
├── src/
│   ├── index.ts                    # 入口點
│   ├── server.ts                   # 主服務器類
│   ├── interfaces/                 # 活動草稿接口
│   │   ├── ActivityDraftBase.ts
│   │   ├── ContentCreationDraft.ts
│   │   ├── GooglerInteractionDraft.ts
│   │   ├── MentoringDraft.ts
│   │   ├── ProductFeedbackDraft.ts
│   │   ├── PublicSpeakingDraft.ts
│   │   ├── StoryDraft.ts
│   │   └── WorkshopDraft.ts
│   └── types/                      # 類型定義
│       ├── ContentType.ts
│       ├── Country.ts
│       ├── EventFormat.ts
│       ├── InteractionFormat.ts
│       ├── InteractionType.ts
│       ├── ProductFeedbackContentType.ts
│       ├── SignificanceType.ts
│       └── Tag.ts
├── dist/                           # 編譯輸出
├── docs/                           # 文檔
│   └── API.md
├── package.json
├── tsconfig.json
└── README.md

🔧 故障排除

錯誤：“Command not found”

• 驗證claude_desktop_config.json中的路徑是否為絕對路徑。
• 確保文件可執行：chmod +x dist/index.js

錯誤：“Authentication failed”

• 驗證.env中的令牌是否正確。
• 令牌必須具有個人API的權限。

錯誤：“ADVOCU_ACCESS_TOKEN is not set”

• 確保.env文件存在於項目根目錄。
• 驗證.env文件中是否正確設置了令牌。

錯誤：“Rate limit exceeded”

• 等待一分鐘後再進行更多請求。
• API每分鐘限制30個請求。

🤝 貢獻指南

1. 分叉項目。
2. 創建功能分支：git checkout -b feature/new-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送到分支：git push origin feature/new-feature
5. 創建拉取請求。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。