倡导者-mcp服务器

Name: 倡导者-mcp服务器
Author: carlosazaustre

作者：carlosazaustre21 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

统一活动报告 MCP 服务器

🎯 概述

一个统一的 MCP（模型上下文协议）服务器，使Google 开发者专家 (GDE) 和微软 MVP能够通过 AI 驱动的对话界面报告他们的活动。

**告别枯燥的手动数据录入！**只需与 Claude 对话并自然提交您的活动——无论是 YouTube 视频、博客文章、会议演讲还是指导会话。

支持的项目

✅ 微软 MVP - 直接与 MVP 门户集成的 API
✅ Google GDE - 与 Advocu API 集成
🔧 两者同时 - 如果您既是 MVP 又是 GDE，请使用一个工具完成所有操作！

🚀 快速开始

先决条件

Node.js 18+
Claude Desktop
至少一个访问令牌（MVP 或 GDE）

安装

选项 1：本地开发（推荐）

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

选项 2：全局安装

npm install -g advocu-mcp-server

配置

编辑您的 Claude Desktop 配置文件：

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

对于 MVP + GDE：

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/绝对路径到/advocu-mcp-server/dist/index.js"],
      "env": {
        "MVP_ACCESS_TOKEN": "您的_mvp_bearer_token",
        "MVP_USER_PROFILE_ID": "您的_mvp_profile_id",
        "ADVOCU_ACCESS_TOKEN": "您的_gde_token",
        "DOCS_DIR": "/绝对路径到/advocu-mcp-server/docs"
      }
    }
  }
}

📚 重要提示：DOCS_DIR 环境变量是必需的，以使文档工具正常工作。将其设置为您安装中 docs 目录的绝对路径。

仅 MVP：

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/绝对路径到/dist/index.js"],
      1. "env": {
        "MVP_ACCESS_TOKEN": "您的_mvp_bearer_token",
        "MVP_USER_PROFILE_ID": "您的_mvp_profile_id",
        "DOCS_DIR": "/绝对路径到/advocu-mcp-server/docs"
      }
    }
  }
}

仅 GDE：

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/绝对路径到/dist/index.js"],
      "env": {
        "ADVOCU_ACCESS_TOKEN": "您的_gde_token",
        "DOCS_DIR": "/绝对路径到/advocu-mcp-server/docs"
      }
    }
  }
}

获取您的令牌

Microsoft MVP 令牌

仅限 Claude Desktop 用户（不包括 Claude Code）：

npm run capture-mvp-token

此工具将：

打开您的默认浏览器到 MVP 门户（您应该已经登录）
显示详细的指令以从 DevTools 中捕获令牌
当提示时粘贴您的令牌
自动更新您的 Claude Desktop 配置文件中的新令牌
不检测浏览器自动化 - 使用您的真实浏览器会话！

Google GDE 令牌

从 Advocu 开发者门户获取您的令牌。

重新启动 Claude Desktop

# 完全退出
Cmd+Q  # macOS
Alt+F4 # Windows

# 然后重新打开 Claude Desktop

查找 🔨 锤子图标以确认工具已加载！

💬 使用示例

只需自然地与 Claude 对话！这里有一些示例：

文档工具

"列出可用文档"

"显示 MVP API 参考"

"有哪些文档可用？"

"获取错误处理文档"

Microsoft MVP 活动

提交视频

"提交我的 YouTube 视频到 Microsoft MVP：
- 标题：React 服务器组件完全指南
- 发布日期：2025年10月9日
- URL：https://youtube.com/watch?v=example
- 直播观看数：12,500
- 按需观看数：12,500
- 场次：1
- 目标受众：开发者，技术决策者
- 我的角色：主持人
- 技术领域：Web 开发
- 描述：全面教程涵盖 React 服务器组件..."

提交博客文章

"添加我最新的博客文章到 MVP：
- 标题：理解 TypeScript 泛型
- 日期：2025-10-01
- URL：https://myblog.com/typescript-generics
- 浏览量：5,000
- 目标受众：开发者
- 角色：作者
- 技术领域：开发工具"

提交会议演讲

"报告我的会议演讲到 MVP：
- 标题：使用 Node.js 构建可扩展的 API
- 日期：2025-09-15
- URL：https://conference.com/my-talk
- 现场参会人数：250
- 场次：1
- 目标受众：开发者，IT 专业人士
- 角色：演讲者
- 技术领域：云与 AI"

Google GDE 活动

"提交我的研讨会到我的 GDE 个人资料：
- 标题：高级 React 模式研讨会
- 类型：研讨会
- 日期：2025-08-20
- 格式：混合
- 国家：美国
- 现场参会人数：50
- 总参会人数：150
- URL：https://workshop.com"

"创建关于 Next.js 14 的 Medium 文章的内容创作草稿"

"报告我与三位开发者关于 TypeScript 最佳实践的指导会话"

🔧 可用工具

文档工具（2）- 始终可用

工具	描述	使用
`list_documentation`	列出所有可用文档	"列出可用文档"
`get_documentation`	获取特定文档文件	"显示 MVP API 参考"

可用文档：

api-reference - MVP 和 GDE 的完整 API 文档
mvp-api-reference - 详细的 MVP API 规范
mvp-fixes-changelog - MVP 集成修复历史
error-handling - 错误处理改进指南
mcp-resources - MCP 资源使用指南

📚 注意：文档工具需要在您的配置中设置 DOCS_DIR。

Microsoft MVP 工具（3）

工具	描述	关键字段
`submit_mvp_video`	视频、网络研讨会、直播	观看数、场次、角色、技术领域
`submit_mvp_blog`	博客文章、文章	观看数、订阅者数、技术领域
`submit_mvp_speaking`	会议演讲、演示	参会人数、场次、技术领域

Google GDE 工具（7）

工具	描述
`submit_gde_content_creation`	文章、视频、播客
`submit_gde_public_speaking`	演讲和演示
`submit_gde_workshop`	培训课程
`submit_gde_mentoring`	指导活动
`submit_gde_product_feedback`	产品反馈
`submit_gde_googler_interaction`	与谷歌员工互动
`submit_gde_story`	成功故事

🔄 令牌刷新

Microsoft MVP 令牌（过期：小时/天）

您的 MVP 令牌定期过期。当您收到 401 错误或令牌过期时：

对于 Claude Desktop 用户：

cd /路径到/advocu-mcp-server
npm run capture-mvp-token

会发生什么：

🌐 您的默认浏览器打开到 MVP 门户
✅ 如果您已经登录，您将立即看到您的帐户
🔐 如果未登录，请使用 Microsoft 登录（支持 2FA）
🛠️ 打开 DevTools（F12 或 Cmd+Option+I）
📝 导航到“添加活动”并填写任意字段
🔍 在网络标签中找到请求 mavenapi-prod.azurewebsites.net
📋 从授权头复制 Bearer 令牌
⌨️ 将令牌粘贴到终端
✅ 您的 Claude Desktop 配置文件将自动更新！
🔄 重新启动 Claude Desktop

优点：

✅ 使用您的真实浏览器（无自动化检测）
✅ 支持 2FA/MFA
✅ 自动更新您的 Claude Desktop 配置文件
✅ 清晰的逐步说明

Google GDE 令牌（过期：较少频繁）

需要时从 Advocu 获取新鲜令牌，并手动更新您的配置。

📋 必要字段参考

MVP 视频活动

{
  title: string;              // 最多 100 字符
  description: string;        // 最多 1000 字符
  date: string;              // YYYY-MM-DD
  url: string;               // 视频 URL
  targetAudience: string[];  // 开发者，学生，IT 专业人士等。
  role: string;              // 主持人，演讲者等。
  technologyFocusArea: string;
  liveStreamViews: number;
  onDemandViews: number;
  numberOfSessions: number;  // 默认：1
  isPrivate: boolean;        // 可选
}

MVP 博客活动

{
  title: string;
  description: string;
  date: string;
  url: string;
  targetAudience: string[];
  role: string;              // 作者，贡献者等。
  technologyFocusArea: string;
  numberOfViews: number;
  subscriberBase: number;    // 可选
  isPrivate: boolean;        // 可选
}

MVP 演讲活动

{
  title: string;
  description: string;
  date: string;
  url: string;
  targetAudience: string[];
  role: string;              // 演讲者，小组成员等。
  technologyFocusArea: string;
  inPersonAttendees: number;
  numberOfSessions: number;
  liveStreamViews: number;   // 可选
  onDemandViews: number;     // 可选
  isPrivate: boolean;        // 可选
}

🏗️ 项目结构

advocu-mcp-server/
├── src/
│   ├── index.ts                    # 入口点
│   ├── unifiedServer.ts            # 主统一服务器（MVP + GDE）
│   ├── server.ts                   # 仅 GDE 的遗留服务器
│   ├── mvpServer.ts                # 独立 MVP 服务器
│   ├── interfaces/                 # 活动接口
│   │   ├── ActivityDraftBase.ts    # GDE 基础接口
│   │   ├── ContentCreationDraft.ts # GDE 内容创作
│   │   ├── ...                     # 其他 GDE 接口
│   │   └── mvp/                    # MVP 接口
│   │       ├── MVPActivityBase.ts
│   │       ├── MVPVideoActivity.ts
│   │       ├── MVPBlogActivity.ts
│   │       └── MVPSpeakingActivity.ts
│   └── types/                      # 类型定义
│       ├── ContentType.ts          # GDE 类型
│       ├── ...
│       └── mvp/                    # MVP 类型
│           ├── MVPActivityType.ts
│           ├── MVPActivityRole.ts
│           └── MVPTargetAudience.ts
├── scripts/
│   ├── capture-mvp-token.ts        # 令牌捕获工具
│   └── README.md                   # 脚本文档
├── dist/                           # 编译输出
└── docs/                           # 📚 文档（文档工具所需）
    ├── API.md                      # 完整 API 参考
    ├── MVP_API_REFERENCE.md        # MVP API 规范
    ├── CHANGELOG_MVP_FIXES.md      # MVP 集成变更日志
    ├── ERROR_HANDLING_IMPROVEMENTS.md  # 错误处理指南
    ├── MCP_RESOURCES.md            # MCP 资源指南
    └── RELEASE_NOTES_v0.2.0.md     # 发布说明

🛠️ 开发

构建

npm run build

开发模式

npm run dev

代码检查和格式化

npm run lint
npm run format

捕获 MVP 令牌

npm run capture-mvp-token

🐛 故障排除

工具未出现在 Claude Desktop 中

检查配置路径：确保您的 claude_desktop_config.json 在正确的位置
验证构建：在项目目录中运行 npm run build
检查日志：重新启动 Claude Desktop 并检查是否有错误
验证令牌：确保至少配置了一个令牌（MVP 或 GDE）

401 未经授权错误（MVP）

您的令牌已过期。运行：

npm run capture-mvp-token

按照说明从 DevTools 中捕获新的令牌，然后重新启动 Claude Desktop。

"至少需要配置 GDE 或 MVP 中的一个"

您需要设置以下之一：

ADVOCU_ACCESS_TOKEN（用于 GDE），或
MVP_ACCESS_TOKEN + MVP_USER_PROFILE_ID（用于 MVP）

如果您既是 MVP 又是 GDE，则可以同时设置这两个！

文档工具无法工作

如果遇到类似“读取资源失败”或“文档未找到”的错误：

检查 DOCS_DIR 是否已设置：确保您已在 Claude Desktop 配置中添加了 DOCS_DIR
验证路径：路径必须是绝对路径并指向 docs 目录
示例："DOCS_DIR": "/Users/yourname/advocu-mcp-server/docs"
检查目录是否存在：运行 ls "$DOCS_DIR" 来验证目录是否存在
重新启动 Claude Desktop：更改配置需要重新启动

示例配置：

{
  "env": {
    "MVP_ACCESS_TOKEN": "...",
    "DOCS_DIR": "/绝对路径到/advocu-mcp-server/docs"
  }
}

MVP 提交失败

检查您的个人资料 ID：确保 MVP_USER_PROFILE_ID 正确
验证令牌：运行 npm run capture-mvp-token 获取新的令牌
检查必要字段：所有必要字段都必须提供
目标受众：必须是一个数组（例如，["开发者"]）

🔒 安全与隐私

令牌存储在本地在您的 Claude Desktop 配置中
切勿将令牌提交到版本控制
captured-api-calls.json 在 .gitignore 中 - 它包含敏感数据
MVP 令牌定期过期以保证安全
令牌从未发送给任何人，除了官方 API

📖 API 文档

Microsoft MVP API

基础 URL：https://mavenapi-prod.azurewebsites.net/api
端点：POST /Activities/
认证：Bearer 令牌
负载：{ "activity": { ...字段 } }

Google GDE API (Advocu)

基础 URL：https://api.advocu.com/personal-api/v1/gde
端点：/activity-drafts/{类型}
认证：Bearer 令牌
速率限制：每分钟 30 次请求

有关详细字段文档，请参阅 docs/API.md。

🤝 贡献

分叉项目
创建功能分支：git checkout -b feature/amazing-feature
提交您的更改（使用常规提交）
推送到分支：git push origin feature/amazing-feature
打开拉取请求

📝 许可证

MIT 许可证 - 详情见 LICENSE 文件。

🙏 致谢

为 Google 开发者专家和微软 MVP 打造
由模型上下文协议 (MCP) 提供动力
与 Advocu 和微软 MVP 门户集成

💡 提示

具体明确：您提供的细节越多，Claude 的表现越好
自然语言：只需描述您做了什么 - Claude 会进行结构化
批量提交：在一个对话中提交多个活动
检查响应：Claude 会显示 API 响应以供验证
**令牌过