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

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)

Google GDE Tools (7)

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

1. Check config path: Ensure your claude_desktop_config.json is in the right location
2. Verify build: Run npm run build in the project directory
3. Check logs: Restart Claude Desktop and check for errors
4. 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":

1. Check DOCS_DIR is set: Make sure you added DOCS_DIR to your Claude Desktop config
2. Verify the path: The path must be absolute and point to the docs directory
3. Example: "DOCS_DIR": "/Users/yourname/advocu-mcp-server/docs"
4. Check directory exists: Run ls "$DOCS_DIR" to verify the directory exists
5. 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

1. Check your profile ID: Make sure MVP_USER_PROFILE_ID is correct
2. Verify token: Run npm run capture-mvp-token to get a fresh token
3. Check required fields: All required fields must be provided
4. 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

1. Fork the project
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes (use conventional commits)
4. Push to the branch: git push origin feature/amazing-feature
5. 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! 🚀