Activity Reporting MCP Server

# 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](https://advocu.com). ### 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 ``` "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:** ```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 ``` 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](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](LICENSE) file for details. --- ## 🙏 Acknowledgments - Built for Google Developer Experts and Microsoft MVPs - Powered by [Model Context Protocol (MCP)](https://modelcontextprotocol.io) - Integrates with [Advocu](https://advocu.com) 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](#-troubleshooting). **Want to add more activity types?** Check out the code structure and submit a PR! 🚀