Advocu MCP Server

🚀 活动报告MCP服务器

本项目助力谷歌开发者专家（GDEs）通过人工智能驱动的对话界面轻松报告他们的活动。通过将Advocu API与模型上下文协议（MCP）集成，GDEs现在可以直接通过人工智能聊天模型或命令行工具提交他们的内容创作、演讲活动、研讨会、指导课程等活动。这简化了报告流程，使其更加直观和便捷，同时满足了GDE计划所需的详细跟踪要求。

这是一个用于向Advocu GDE API报告活动的模型上下文协议（MCP）服务器。

🚀 快速开始

📦 安装指南

使用NPM

npm install -g advocu-mcp-server

使用npx（推荐：无需安装）

npx advocu-mcp-server

⚙️ 配置

前提条件

• Node.js 18+
• Advocu GDE API访问令牌

步骤1：配置Claude桌面版

编辑Claude桌面版配置文件：

• 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桌面版

关闭并重新打开Claude桌面版以加载新配置。

🔄 替代方案：本地开发设置

如果您想为项目做贡献或修改服务器：

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

然后使用本地路径配置Claude桌面版：

{
  "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_content_creation - 报告内容创作活动
• submit_public_speaking - 报告演讲活动
• submit_workshop - 报告研讨会活动
• submit_mentoring - 报告指导活动
• submit_product_feedback - 报告产品反馈提交情况
• submit_googler_interaction - 报告与谷歌员工的互动情况
• submit_story - 报告成功案例

💻 使用示例

基础用法

在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文件。