Activity Reporting MCP Server

统一活动报告MCP服务器

🎯 概述

一个统一的MCP（模型上下文协议）服务器，支持 谷歌开发专家（GDE）和微软MVP 通过人工智能驱动的对话界面报告他们的活动。

停止无聊的手动数据输入！ 只需与克劳德交谈，自然地提交你的活动——无论是YouTube视频、博客文章、会议演讲还是指导课程。

支持的程序

• ✅ 微软最有价值专家 -API与MVP门户的直接集成
• ✅ 谷歌GDE -与Advocu API集成
• 🔧 两者同时 -如果你既是MVP又是GDE，那就用一个工具做所有事情吧！

______________________________________________________________________

🚀 快速开始

先决条件

• Node.js 18+
• 克劳德桌面
• 至少一个访问令牌（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 视窗: %APPDATA%/Claude/claude_desktop_config.json

对于MVP+GDE：

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/absolute/path/to/advocu-mcp-server/dist/index.js"],
      "env": {
        "MVP_ACCESS_TOKEN": "your_mvp_bearer_token",
        "MVP_USER_PROFILE_ID": "your_mvp_profile_id",
        "ADVOCU_ACCESS_TOKEN": "your_gde_token",
        "DOCS_DIR": "/absolute/path/to/advocu-mcp-server/docs"
      }
    }
  }
}

📚 重要：The DOCS_DIR 环境变量为 必需的 使文档工具正常工作。将其设置为 docs 安装中的目录。

仅MVP：

{
  "mcpServers": {
    "activity-reporting": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "MVP_ACCESS_TOKEN": "your_mvp_bearer_token",
        "MVP_USER_PROFILE_ID": "your_mvp_profile_id",
        "DOCS_DIR": "/absolute/path/to/advocu-mcp-server/docs"
      }
    }
  }
}

仅限GDE：

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

获取您的代币

微软MVP代币

仅适用于Claude Desktop用户 （非克劳德代码）：

npm run capture-mvp-token

此工具将：

1. 打开默认浏览器 转到MVP门户（您应该已经登录）
2. 向您展示从DevTools捕获令牌的详细说明
3. 粘贴您的令牌 当系统提示时
4. 自动更新您的Claude Desktop配置文件 使用新令牌
5. 无浏览器自动化检测-使用您的真实浏览器会话！

Google GDE 令牌

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

重新启动克劳德桌面

# Quit completely
Cmd+Q  # macOS
Alt+F4 # Windows

# Then reopen Claude Desktop

寻找🔨 锤子图标，确认工具已加载！

______________________________________________________________________

💬 用法示例

自然地和克劳德谈谈！以下是示例：

文档工具

"List available documentation"

"Show me the MVP API reference"

"What documentation is available?"

"Get the error handling documentation"

微软MVP活动

提交视频

"Submit my YouTube video to Microsoft MVP:
- Title: Complete Guide to React Server Components
- Published: October 9, 2025
- URL: https://youtube.com/watch?v=example
- Livestream views: 12,500
- On-demand views: 12,500
- Sessions: 1
- Target audience: Developers, Technical Decision Makers
- My role: Host
- Tech area: Web Development
- Description: A comprehensive tutorial covering React Server Components..."

提交博客文章

"Add my latest blog post to MVP:
- Title: Understanding TypeScript Generics
- Date: 2025-10-01
- URL: https://myblog.com/typescript-generics
- Views: 5,000
- Target audience: Developers
- Role: Author
- Tech area: Developer Tools"

提交会议演讲

"Report my conference presentation to MVP:
- Title: Building Scalable APIs with Node.js
- Date: 2025-09-15
- URL: https://conference.com/my-talk
- In-person attendees: 250
- Sessions: 1
- Target audience: Developers, IT Pros
- Role: Speaker
- Tech area: Cloud & AI"

谷歌GDE活动

"Submit my workshop to my GDE profile:
- Title: Advanced React Patterns Workshop
- Type: Workshop
- Date: 2025-08-20
- Format: Hybrid
- Country: United States
- In-person attendees: 50
- Total attendees: 150
- URL: https://workshop.com"

"Create a content creation draft for my Medium article about Next.js 14"

"Report my mentoring session with 3 developers about TypeScript best practices"

______________________________________________________________________

🔧 可用工具

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

可用文件：

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

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

微软MVP工具（3）

Google GDE 工具 (7)

______________________________________________________________________

🔄 令牌刷新

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

您的MVP代币定期到期。当你收到401错误或你的代币过期时：

对于Claude Desktop用户：

cd /path/to/advocu-mcp-server
npm run capture-mvp-token

发生了什么：

1. 🌐 默认浏览器打开MVP门户
2. ✅ 如果您已经登录，您将立即看到您的帐户
3. 🔐 如果未登录，请使用Microsoft登录（支持2FA）
4. 🛠️ 打开DevTools（F12或Cmd+选项+I）
5. 📝 导航到“添加活动”并填写任何字段
6. 🔍 在“网络”选项卡中，找到以下请求 mavenapi-prod.azurewebsites.net
7. 📋 从Authorization标头复制Bearer令牌
8. ⌨️ 将令牌粘贴到终端中
9. ✅ 您的Claude Desktop配置文件会自动更新！
10. 🔄 重新启动克劳德桌面

优势：

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

谷歌GDE代币（到期频率：较低）

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

______________________________________________________________________

📋 必填字段参考

MVP视频活动

{
  title: string;              // Max 100 chars
  description: string;        // Max 1000 chars
  date: string;              // YYYY-MM-DD
  url: string;               // Video URL
  targetAudience: string[];  // Developer, Student, IT Pro, etc.
  role: string;              // Host, Presenter, etc.
  technologyFocusArea: string;
  liveStreamViews: number;
  onDemandViews: number;
  numberOfSessions: number;  // Default: 1
  isPrivate: boolean;        // Optional
}

MVP博客活动

{
  title: string;
  description: string;
  date: string;
  url: string;
  targetAudience: string[];
  role: string;              // Author, Contributor, etc.
  technologyFocusArea: string;
  numberOfViews: number;
  subscriberBase: number;    // Optional
  isPrivate: boolean;        // Optional
}

MVP演讲活动

{
  title: string;
  description: string;
  date: string;
  url: string;
  targetAudience: string[];
  role: string;              // Speaker, Panelist, etc.
  technologyFocusArea: string;
  inPersonAttendees: number;
  numberOfSessions: number;
  liveStreamViews: number;   // Optional
  onDemandViews: number;     // Optional
  isPrivate: boolean;        // Optional
}

______________________________________________________________________

🏗️ 项目结构

advocu-mcp-server/
├── src/
│   ├── index.ts                    # Entry point
│   ├── unifiedServer.ts            # Main unified server (MVP + GDE)
│   ├── server.ts                   # Legacy GDE-only server
│   ├── mvpServer.ts                # Standalone MVP server
│   ├── interfaces/                 # Activity interfaces
│   │   ├── ActivityDraftBase.ts    # GDE base interface
│   │   ├── ContentCreationDraft.ts # GDE content creation
│   │   ├── ...                     # Other GDE interfaces
│   │   └── mvp/                    # MVP interfaces
│   │       ├── MVPActivityBase.ts
│   │       ├── MVPVideoActivity.ts
│   │       ├── MVPBlogActivity.ts
│   │       └── MVPSpeakingActivity.ts
│   └── types/                      # Type definitions
│       ├── ContentType.ts          # GDE types
│       ├── ...
│       └── mvp/                    # MVP types
│           ├── MVPActivityType.ts
│           ├── MVPActivityRole.ts
│           └── MVPTargetAudience.ts
├── scripts/
│   ├── capture-mvp-token.ts        # Token capture tool
│   └── README.md                   # Script documentation
├── dist/                           # Compiled output
└── docs/                           # 📚 Documentation (required for doc tools)
    ├── API.md                      # Complete API reference
    ├── MVP_API_REFERENCE.md        # MVP API specifications
    ├── CHANGELOG_MVP_FIXES.md      # MVP integration changelog
    ├── ERROR_HANDLING_IMPROVEMENTS.md  # Error handling guide
    ├── MCP_RESOURCES.md            # MCP resources guide
    └── RELEASE_NOTES_v0.2.0.md     # Release notes

______________________________________________________________________

🛠️ 发展

构建

npm run build

发展模式

npm run dev

棉绒和格式

npm run lint
npm run format

获取MVP代币

npm run capture-mvp-token

______________________________________________________________________

🐛 故障排除

工具未出现在Claude Desktop中

1. 检查配置路径：确保您的 claude_desktop_config.json 位置正确
2. 验证构建：运行 npm run build 在项目目录中
3. 检查日志：重新启动Claude Desktop并检查错误
4. 验证令牌：确保至少配置了一个令牌（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，两者都可以设置！

文档工具不工作

如果您收到“读取资源失败”或“找不到文档”等错误：

1. 检查 DOCS_DIR 已设置：确保您已添加 DOCS_DIR 到您的Claude桌面配置
2. 验证路径：路径必须为 绝对的 并指向 docs 目录
3. 示例: "DOCS_DIR": "/Users/yourname/advocu-mcp-server/docs"
4. 检查目录是否存在：运行 ls "$DOCS_DIR" 验证目录是否存在
5. 重新启动克劳德桌面：更改配置需要重新启动

配置示例：

{
  "env": {
    "MVP_ACCESS_TOKEN": "...",
    "DOCS_DIR": "/absolute/path/to/advocu-mcp-server/docs"
  }
}

MVP提交失败

1. 检查您的个人资料ID：确保 MVP_USER_PROFILE_ID 是正确的
2. 验证令牌：运行 npm run capture-mvp-token 获取一个新的代币
3. 检查必填字段：必须提供所有必填字段
4. 目标受众：必须是数组（例如。， ["Developer"])

______________________________________________________________________

🔒 安全与隐私

• 令牌存储在本地 在您的Claude Desktop配置中
• 从不提交代币 到版本控制
• captured-api-calls.json 在...里 .gitignore -它包含敏感数据
• MVP代币到期 定期安全
• 代币从不发送 除了官方API之外的任何人

______________________________________________________________________

📖 API文档

微软MVP API

• 基本URL: https://mavenapi-prod.azurewebsites.net/api
• 端点: POST /Activities/
• 认证：不记名代币
• 有效载荷: { "activity": { ...fields } }

Google GDE API（支持）

• 基本URL: https://api.advocu.com/personal-api/v1/gde
• 端点: /activity-drafts/{type}
• 认证：不记名代币
• 速率限制：30个请求/分钟

有关详细的现场文档，请参阅 docs/API.md文件.

______________________________________________________________________

🤝 贡献

1. 分叉项目
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 提交您的更改（使用常规提交）
4. 推到分支： git push origin feature/amazing-feature
5. 打开拉取请求

______________________________________________________________________

📝 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

• 专为谷歌开发专家和微软MVP打造
• 由...驱动 模型上下文协议（MCP）
• 与集成 律师 微软MVP门户

______________________________________________________________________

💡 提示

• 要具体你向克劳德提供的细节越多越好
• 自然语言：只要描述一下你做了什么——克劳德会安排好的
• 批量提交：在一次对话中提交多个活动
• 检查回复：Claude将向您展示API响应以进行验证
• 令牌过期？ 跑 npm run capture-mvp-token 粘贴您的新令牌-需要30秒

______________________________________________________________________

问题或议题？ 在GitHub上打开问题或查看 故障排除部分.

想添加更多活动类型吗？ 查看代码结构并提交PR！ 🚀