Advocu

Unified Activity Reporting MCP Server

🎯 Overview

A unified MCP (Model Context Protocol) server that enables both Google Developer Experts (GDEs) and Microsoft MVPs to report their activities through AI-powered conversational interfaces.

Stop the boring manual data entry! Just talk to Claude and submit your activities naturally - whether it's a YouTube video, blog post, conference talk, or mentoring session.

Supported Programs

• ✅ Microsoft MVP - Direct API integration with the MVP portal
• ✅ Google GDE - Integration with Advocu API
• 🔧 Both at once - If you're both an MVP and GDE, use one tool for everything!

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• Claude Desktop
• At least one access token (MVP or GDE)

Installation

Option 1: Local Development (Recommended)

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

Option 2: Global Install

npm install -g advocu-mcp-server

Configuration

Edit your Claude Desktop config file:

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

For Both 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"
      }
    }
  }
}

📚 Important: The DOCS_DIR environment variable is required for documentation tools to work. Set it to the absolute path of the docs directory in your installation.

MVP Only:

{
  "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 Only:

{
  "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"
      }
    }
  }
}

Get Your Tokens

Microsoft MVP Token

For Claude Desktop users only (not Claude Code):

npm run capture-mvp-token

This tool will:

1. Open your default browser to the MVP portal (you should already be logged in)
2. Show you detailed instructions to capture the token from DevTools
3. Paste your token when prompted
4. Automatically update your Claude Desktop config file with the new token
5. No browser automation detection - uses your real browser session!

Google GDE Token

Get your token from the Advocu Developer Portal.

Restart Claude Desktop

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

# Then reopen Claude Desktop

Look for the 🔨 hammer icon to confirm tools are loaded!

---

💬 Usage Examples

Just talk to Claude naturally! Here are examples:

Documentation Tools

"List available documentation"

"Show me the MVP API reference"

"What documentation is available?"

"Get the error handling documentation"

Microsoft MVP Activities

Submit a Video

"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..."

Submit a Blog Post

"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"

Submit a Conference Talk

"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"

Google GDE Activities

"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"

---

🔧 Available Tools

Documentation Tools (2) - Always Available

Tool	Description	Usage
list_documentation	List all available documentation	"List available documentation"
get_documentation	Get a specific documentation file	"Show me the MVP API reference"

Available Documents:

• api-reference - Complete API documentation for MVP and GDE
• mvp-api-reference - Detailed MVP API specifications
• mvp-fixes-changelog - MVP integration fixes history
• error-handling - Error handling improvements guide
• mcp-resources - MCP resources usage guide

📚 Note: Documentation tools require DOCS_DIR to be set in your configuration.

Microsoft MVP Tools (3)

Tool	Description	Key Fields
submit_mvp_video	Videos, webinars, livestreams	views, sessions, role, tech area
submit_mvp_blog	Blog posts, articles	views, subscribers, tech area
submit_mvp_speaking	Conference talks, presentations	attendees, sessions, tech area

Google GDE Tools (7)

Tool	Description
submit_gde_content_creation	Articles, videos, podcasts
submit_gde_public_speaking	Talks and presentations
submit_gde_workshop	Training sessions
submit_gde_mentoring	Mentoring activities
submit_gde_product_feedback	Product feedback
submit_gde_googler_interaction	Google employee interactions
submit_gde_story	Success stories

---

🔄 Token Refresh

Microsoft MVP Token (Expires: Hours/Days)

Your MVP token expires regularly. When you get a 401 error or your token expires:

For Claude Desktop users:

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

What happens:

1. 🌐 Your default browser opens to the MVP portal
2. ✅ If you're already logged in, you'll see your account immediately
3. 🔐 If not logged in, log in with Microsoft (2FA supported)
4. 🛠️ Open DevTools (F12 or Cmd+Option+I)
5. 📝 Navigate to "Add activity" and fill any field
6. 🔍 In Network tab, find the request to mavenapi-prod.azurewebsites.net
7. 📋 Copy the Bearer token from the Authorization header
8. ⌨️ Paste the token in the terminal
9. ✅ Your Claude Desktop config file is automatically updated!
10. 🔄 Restart Claude Desktop

Advantages:

• ✅ Uses your real browser (no automation detection)
• ✅ Works with 2FA/MFA
• ✅ Automatically updates your Claude Desktop config file
• ✅ Clear step-by-step instructions

Google GDE Token (Expires: Less frequently)

Get a fresh token from Advocu when needed and update your config manually.

---

📋 Required Fields Reference

MVP Video Activity

{
  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 Blog Activity

{
  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 Speaking Activity

{
  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
}

---

🏗️ Project Structure

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
│           └─

---

*README truncated. [View full README on GitHub](https://github.com/carlosazaustre/advocu-mcp-server).*