@iflow-mcp/advocu-mcp-server

v0.2.0

Published

9 days ago

Unified MCP Server for Google GDE (Advocu) and Microsoft MVP Activity Reporting

0High
0Medium
0Low

chatflowdev

qystart

gde mvp advocu microsoft-mvp mcp server model-context-protocol google-developer-expert activity-reporting ai claude cli developer-program

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:

Open your default browser to the MVP portal (you should already be logged in)
Show you detailed instructions to capture the token from DevTools
Paste your token when prompted
Automatically update your Claude Desktop config file with the new token
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:

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

🛠️ Development

Build

npm run build

Development Mode

npm run dev

Lint and Format

npm run lint
npm run format

Capture MVP Token

npm run capture-mvp-token

🐛 Troubleshooting

Tools Don't Appear in Claude Desktop

Check config path: Ensure your claude_desktop_config.json is in the right location
Verify build: Run npm run build in the project directory
Check logs: Restart Claude Desktop and check for errors
Verify tokens: Make sure at least one token (MVP or GDE) is configured

401 Unauthorized Error (MVP)

Your token expired. Run:

npm run capture-mvp-token

Follow the instructions to capture a fresh token from DevTools, then restart Claude Desktop.

"At least one of GDE or MVP must be configured"

You need to set either:

ADVOCU_ACCESS_TOKEN (for GDE), or
MVP_ACCESS_TOKEN + MVP_USER_PROFILE_ID (for MVP)

Both can be set if you're both an MVP and GDE!

Documentation Tools Not Working

If you get errors like "Failed to read resource" or "Documentation not found":

Check DOCS_DIR is set: Make sure you added DOCS_DIR to your Claude Desktop config
Verify the path: The path must be absolute and point to the docs directory
Example: "DOCS_DIR": "/Users/yourname/advocu-mcp-server/docs"
Check directory exists: Run ls "$DOCS_DIR" to verify the directory exists
Restart Claude Desktop: Changes to config require a restart

Example config:

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

MVP Submission Fails

Check your profile ID: Make sure MVP_USER_PROFILE_ID is correct
Verify token: Run npm run capture-mvp-token to get a fresh token
Check required fields: All required fields must be provided
Target audience: Must be an array (e.g., ["Developer"])

🔒 Security & Privacy

Tokens are stored locally in your Claude Desktop config
Never commit tokens to version control
captured-api-calls.json is in .gitignore - it contains sensitive data
MVP tokens expire regularly for security
Tokens are never sent to anyone except the official APIs

📖 API Documentation

Microsoft MVP API

Base URL: https://mavenapi-prod.azurewebsites.net/api
Endpoint: POST /Activities/
Authentication: Bearer token
Payload: { "activity": { ...fields } }

Google GDE API (Advocu)

Base URL: https://api.advocu.com/personal-api/v1/gde
Endpoints: /activity-drafts/{type}
Authentication: Bearer token
Rate Limit: 30 requests/minute

For detailed field documentation, see docs/API.md.

🤝 Contributing

Fork the project
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes (use conventional commits)
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built for Google Developer Experts and Microsoft MVPs
Powered by Model Context Protocol (MCP)
Integrates with Advocu and Microsoft MVP Portal

💡 Tips

Be specific: The more details you provide to Claude, the better
Natural language: Just describe what you did - Claude will structure it
Batch submissions: Submit multiple activities in one conversation
Check responses: Claude will show you the API response for verification
Token expires? Just run npm run capture-mvp-token and paste your new token - takes 30 seconds

Questions or issues? Open an issue on GitHub or check the troubleshooting section.

Want to add more activity types? Check out the code structure and submit a PR! 🚀