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)

bash

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

Option 2: Global Install

bash

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:

json

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

json

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

json

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

bash

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

bash

# 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

code

"List available documentation"

code

"Show me the MVP API reference"

code

"What documentation is available?"

code

"Get the error handling documentation"

Microsoft MVP Activities

Submit a Video

code

"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

code

"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

code

"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

code

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

code

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

code

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

bash

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

typescript

{
  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

typescript

{
  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

typescript

{
  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

code

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

bash

npm run build

Development Mode

bash

npm run dev

Lint and Format

bash

npm run lint
npm run format

Capture MVP Token

bash

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:

bash

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:

json

{
  "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! 🚀

Advocu Mcp Server

Documentation

Unified Activity Reporting MCP Server

🎯 Overview

Supported Programs

🚀 Quick Start

Prerequisites

Installation

Option 1: Local Development (Recommended)

Option 2: Global Install

Configuration

For Both MVP + GDE:

MVP Only:

GDE Only:

Get Your Tokens

Microsoft MVP Token

Google GDE Token

Restart Claude Desktop

💬 Usage Examples

Documentation Tools

Microsoft MVP Activities

Submit a Video

Submit a Blog Post

Submit a Conference Talk

Google GDE Activities

🔧 Available Tools

Documentation Tools (2) - Always Available

Microsoft MVP Tools (3)

Google GDE Tools (7)

🔄 Token Refresh

Microsoft MVP Token (Expires: Hours/Days)

Google GDE Token (Expires: Less frequently)

📋 Required Fields Reference

MVP Video Activity

MVP Blog Activity

MVP Speaking Activity

🏗️ Project Structure

🛠️ Development

Build

Development Mode

Lint and Format

Capture MVP Token

🐛 Troubleshooting

Tools Don't Appear in Claude Desktop

401 Unauthorized Error (MVP)

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

Documentation Tools Not Working

MVP Submission Fails

🔒 Security & Privacy

📖 API Documentation

Microsoft MVP API

Google GDE API (Advocu)

🤝 Contributing

📝 License

🙏 Acknowledgments

💡 Tips

Similar MCP

Metmuseum Mcp

Mcp Server Aws Sso

Mcp Ipfs

Liveblocks Mcp Server

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Metmuseum Mcp

Mcp Server Aws Sso

Mcp Ipfs

Liveblocks Mcp Server

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare