claude-mpm 5.4.22__py3-none-any.whl → 5.6.34__py3-none-any.whl

claude_mpm/skills/bundled/main/internal-comms/examples/faq-answers.md

@@ -0,0 +1,30 @@
+## Instructions
+You are an assistant for answering questions that are being asked across the company. Every week, there are lots of questions that get asked across the company, and your goal is to try to summarize what those questions are. We want our company to be well-informed and on the same page, so your job is to produce a set of frequently asked questions that our employees are asking and attempt to answer them. Your singular job is to do two things:
+
+- Find questions that are big sources of confusion for lots of employees at the company, generally about things that affect a large portion of the employee base
+- Attempt to give a nice summarized answer to that question in order to minimize confusion.
+
+Some examples of areas that may be interesting to folks: recent corporate events (fundraising, new executives, etc.), upcoming launches, hiring progress, changes to vision or focus, etc.
+
+
+## Tools Available
+You should use the company's available tools, where communication and work happens. For most companies, it looks something like this:
+- Slack: questions being asked across the company - it could be questions in response to posts with lots of responses, questions being asked with lots of reactions or thumbs up to show support, or anything else to show that a large number of employees want to ask the same things
+- Email: emails with FAQs written directly in them can be a good source as well
+- Documents: docs in places like Google Drive, linked on calendar events, etc. can also be a good source of FAQs, either directly added or inferred based on the contents of the doc
+
+## Formatting
+The formatting should be pretty basic:
+
+- *Question*: [insert question - 1 sentence]
+- *Answer*: [insert answer - 1-2 sentence]
+
+## Guidance
+Make sure you're being holistic in your questions. Don't focus too much on just the user in question or the team they are a part of, but try to capture the entire company. Try to be as holistic as you can in reading all the tools available, producing responses that are relevant to all at the company.
+
+## Answer Guidelines
+- Base answers on official company communications when possible
+- If information is uncertain, indicate that clearly
+- Link to authoritative sources (docs, announcements, emails)
+- Keep tone professional but approachable
+- Flag if a question requires executive input or official response

claude_mpm/skills/bundled/main/internal-comms/examples/general-comms.md

@@ -0,0 +1,16 @@
+  ## Instructions
+  You are being asked to write internal company communication that doesn't fit into the standard formats (3P
+  updates, newsletters, or FAQs).
+
+  Before proceeding:
+  1. Ask the user about their target audience
+  2. Understand the communication's purpose
+  3. Clarify the desired tone (formal, casual, urgent, informational)
+  4. Confirm any specific formatting requirements
+
+  Use these general principles:
+  - Be clear and concise
+  - Use active voice
+  - Put the most important information first
+  - Include relevant links and references
+  - Match the company's communication style

claude_mpm/skills/bundled/main/mcp-builder/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: mcp-builder
+description: Create high-quality MCP servers that enable LLMs to effectively interact with external services. Use when building MCP integrations for APIs or services in Python (FastMCP) or Node/TypeScript (MCP SDK).
+license: Complete terms in LICENSE.txt
+progressive_disclosure:
+  entry_point:
+    summary: "Build agent-friendly MCP servers through research-driven design, thoughtful implementation, and evaluation-based iteration"
+    when_to_use: "When integrating external APIs/services via MCP protocol. Prioritize agent workflows over API wrappers, optimize for context efficiency, design actionable errors."
+    quick_start: "1. Research protocol & API docs 2. Plan agent-centric tools 3. Implement with validation 4. Create evaluations 5. Iterate based on agent feedback"
+  references:
+    - design_principles.md
+    - workflow.md
+    - mcp_best_practices.md
+    - python_mcp_server.md
+    - node_mcp_server.md
+    - evaluation.md
+---
+
+# MCP Server Development Guide
+
+## Overview
+
+Build high-quality MCP (Model Context Protocol) servers that enable LLMs to accomplish real-world tasks through well-designed tools. Quality is measured not by API coverage, but by how effectively agents can use your tools to complete realistic workflows.
+
+**Core insight:** MCP servers expose tools for AI agents, not human users. Design for agent constraints (limited context, no visual UI, workflow-oriented) rather than human convenience.
+
+## When to Use This Skill
+
+Activate when:
+- Building MCP servers for external API integration
+- Adding tools to existing MCP servers
+- Improving MCP server tool design for better agent usability
+- Creating evaluations to test MCP server effectiveness
+- Debugging why agents struggle with your MCP tools
+
+**Language Support:**
+- Python: FastMCP framework (recommended for rapid development)
+- Node/TypeScript: MCP SDK (recommended for production services)
+
+## The Iron Law
+
+```
+DESIGN FOR AGENTS, NOT HUMANS
+
+Every tool must optimize for:
+- Context efficiency (agents have limited tokens)
+- Workflow completion (not just API calls)
+- Actionable errors (guide agents to success)
+- Natural task subdivision (how agents think)
+```
+
+If your tools are just thin API wrappers, you're violating the Iron Law.
+
+## Core Principles
+
+1. **Agent-Centric Design First**: Study design principles before coding. Tools should enable workflows, not mirror APIs.
+
+2. **Research-Driven Planning**: Load MCP docs, SDK docs, and exhaustive API documentation before writing code.
+
+3. **Evaluation-Based Iteration**: Create realistic evaluations early. Let agent feedback drive improvements.
+
+4. **Context Optimization**: Every response token matters. Default to concise, offer detailed when needed.
+
+5. **Actionable Errors**: Error messages should teach agents correct usage patterns.
+
+## Quick Start
+
+### Phase 1: Research and Planning (40% of effort)
+1. **Study Design Principles**: Load [design_principles.md](./reference/design_principles.md) to understand agent-centric design
+2. **Load Protocol Docs**: Fetch `https://modelcontextprotocol.io/llms-full.txt` for MCP specification
+3. **Study SDK Docs**: Load Python or TypeScript SDK documentation from GitHub
+4. **Study API Exhaustively**: Read ALL API documentation, endpoints, authentication, rate limits
+5. **Create Implementation Plan**: Define tools, shared utilities, pagination strategy, error handling
+
+See [workflow.md](./reference/workflow.md) for complete Phase 1 steps.
+
+### Phase 2: Implementation (30% of effort)
+1. **Setup Project**: Create structure following language-specific guide
+2. **Build Shared Utilities**: API helpers, error handlers, formatters BEFORE tools
+3. **Implement Tools**: Use Pydantic (Python) or Zod (TypeScript) for validation
+4. **Follow Best Practices**: Load language-specific guide for patterns
+
+See [workflow.md](./reference/workflow.md) for complete Phase 2 steps and language guides.
+
+### Phase 3: Review and Refine (15% of effort)
+1. **Code Quality Review**: Check DRY, composability, consistency, type safety
+2. **Test Build**: Verify syntax, imports, build process
+3. **Quality Checklist**: Use language-specific checklist
+
+See [workflow.md](./reference/workflow.md) for complete Phase 3 steps.
+
+### Phase 4: Create Evaluations (15% of effort)
+1. **Understand Purpose**: Evaluations test if agents can answer realistic questions using your tools
+2. **Create 10 Questions**: Complex, read-only, independent, verifiable questions
+3. **Verify Answers**: Solve yourself to ensure stability and correctness
+4. **Run Evaluation**: Use provided scripts to test agent effectiveness
+
+See [evaluation.md](./reference/evaluation.md) for complete evaluation guidelines.
+
+## Navigation
+
+### Core Design and Workflow
+- **[🎯 Design Principles](./reference/design_principles.md)** - Agent-centric design philosophy: workflows over APIs, context optimization, actionable errors, natural task subdivision. Read FIRST before implementation.
+
+- **[🔄 Complete Workflow](./reference/workflow.md)** - Detailed 4-phase development process with step-by-step instructions, decision trees, and when to load each reference file.
+
+### Universal MCP Guidelines
+- **[📋 MCP Best Practices](./reference/mcp_best_practices.md)** - Naming conventions, response formats, pagination, character limits, security, tool annotations, error handling. Applies to all MCP servers.
+
+### Language-Specific Implementation
+- **[🐍 Python Implementation](./reference/python_mcp_server.md)** - FastMCP patterns, Pydantic validation, async/await, complete examples, quality checklist. Load during Phase 2 for Python servers.
+
+- **[⚡ TypeScript Implementation](./reference/node_mcp_server.md)** - MCP SDK patterns, Zod validation, project structure, complete examples, quality checklist. Load during Phase 2 for TypeScript servers.
+
+### Evaluation and Testing
+- **[✅ Evaluation Guide](./reference/evaluation.md)** - Creating realistic questions, answer verification, XML format, running evaluations, interpreting results. Load during Phase 4.
+
+## Key Reminders
+
+- **Research First**: Spend 40% of time researching before coding
+- **Agent-Centric**: Design for AI workflows, not API completeness
+- **Context Efficient**: Every token counts - default concise, offer detailed
+- **Actionable Errors**: Guide agents to correct usage
+- **Shared Utilities**: Extract common code - avoid duplication
+- **Evaluation-Driven**: Create evals early, iterate based on feedback
+- **MCP Servers Block**: Never run servers directly - use evaluation harness or tmux
+
+## Red Flags - STOP
+
+If you catch yourself:
+- "Just wrapping these API endpoints directly"
+- "Returning all available data fields"
+- "Error message just says what failed" (not how to fix)
+- Starting implementation without reading design principles
+- Coding before loading MCP protocol documentation
+- Creating tools without knowing agent use cases
+- Skipping evaluation creation
+- Running `python server.py` directly (will hang forever)
+
+**ALL of these mean: STOP. Return to design principles and workflow.**
+
+## Integration with Other Skills
+
+- **systematic-debugging**: Debug MCP server issues methodically
+- **test-driven-development**: Create failing tests before implementation
+- **verification-before-completion**: Verify build succeeds before claiming completion
+- **defense-in-depth**: Add input validation at multiple layers
+
+## Real-World Impact
+
+From MCP server development experience:
+- Well-designed servers: 80-90% task completion rate by agents
+- API wrapper approach: 30-40% task completion rate
+- Context-optimized responses: 3x more information in same token budget
+- Actionable errors: 60% reduction in agent retry attempts
+- Evaluation-driven iteration: 2-3x improvement in agent success rate
+
+---
+
+**Remember:** The quality of an MCP server is measured by how well it enables LLMs to accomplish realistic tasks, not by how comprehensively it wraps an API.

claude_mpm/skills/bundled/main/mcp-builder/reference/design_principles.md

@@ -0,0 +1,412 @@
+# Agent-Centric Design Principles for MCP Servers
+
+## Overview
+
+Before implementing any MCP server, understand how to design tools for AI agents. Agents are fundamentally different users than humans - they have limited context, no visual UI, and think in terms of workflows rather than API calls.
+
+**Core Philosophy:** Build thoughtful, high-impact workflow tools, not API endpoint wrappers.
+
+---
+
+## Why Agent-Centric Design Matters
+
+MCP servers expose tools that AI agents use to accomplish tasks. The quality of your server is measured by how effectively agents complete realistic workflows, not by API coverage.
+
+**Key Differences from Human-Oriented Design:**
+
+| Human Users | AI Agents |
+|-------------|-----------|
+| Visual UI navigation | No visual interface |
+| Unlimited attention | Limited context window |
+| Can ask clarifying questions | Must work with available information |
+| Tolerate verbose responses | Need concise, high-signal data |
+| Learn from documentation | Learn from tool descriptions and errors |
+
+---
+
+## The Five Design Principles
+
+### 1. Build for Workflows, Not Just API Endpoints
+
+**The Problem:**
+Directly wrapping API endpoints creates tools that are too granular for agents to use effectively. Agents must make many calls to accomplish simple tasks.
+
+**The Solution:**
+Consolidate related operations into workflow-oriented tools that accomplish complete tasks.
+
+**Examples:**
+
+❌ **Poor Design (API Wrapper):**
+```
+check_calendar_availability(date, time)
+create_calendar_event(date, time, title, description)
+send_notification(user_id, message)
+```
+Agent must: Check availability → Create event → Send notification (3 separate calls)
+
+✅ **Good Design (Workflow-Oriented):**
+```
+schedule_event(date, time, title, description, attendees)
+  - Checks availability automatically
+  - Creates event if slot is free
+  - Notifies attendees
+  - Returns single consolidated result
+```
+Agent makes 1 call to complete the workflow.
+
+**Guidelines:**
+- Identify common multi-step workflows users perform
+- Combine related operations that always happen together
+- Provide atomic operations for complex use cases
+- Let tools handle internal coordination and error recovery
+
+### 2. Optimize for Limited Context
+
+**The Problem:**
+Agents have constrained context windows. Verbose responses waste precious tokens and reduce what agents can accomplish.
+
+**The Solution:**
+Return high-signal information by default. Provide options for detail levels.
+
+**Examples:**
+
+❌ **Poor Design (Information Dump):**
+```json
+{
+  "user": {
+    "id": "U123456",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "profile": {
+      "avatar_urls": {
+        "small": "https://...",
+        "medium": "https://...",
+        "large": "https://...",
+        "xlarge": "https://..."
+      },
+      "bio": "Lorem ipsum...",
+      "location": "San Francisco",
+      "timezone": "America/Los_Angeles",
+      "created_at": 1609459200,
+      "updated_at": 1609459200,
+      "preferences": {...},
+      "settings": {...}
+    }
+  }
+}
+```
+15+ fields returned when agent only needs name and email.
+
+✅ **Good Design (High-Signal Default):**
+```json
+{
+  "user": {
+    "id": "U123456",
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+Concise by default. Add `detail_level="full"` parameter for complete data when needed.
+
+**Guidelines:**
+- Default to concise responses with essential information
+- Provide `response_format` parameter: "concise" vs "detailed"
+- Use human-readable identifiers (names) over technical codes (IDs) when possible
+- Support Markdown for human readability, JSON for programmatic processing
+- Implement character limits (typically 25,000) with truncation guidance
+- Respect pagination limits strictly - never load all results
+
+### 3. Design Actionable Error Messages
+
+**The Problem:**
+Generic error messages tell agents what failed but not how to fix it. Agents get stuck or waste attempts guessing.
+
+**The Solution:**
+Every error should guide agents toward correct usage with specific next steps.
+
+**Examples:**
+
+❌ **Poor Design (Diagnostic Only):**
+```
+"Error: Invalid parameters"
+"Error: Request failed"
+"Error: Too many results"
+```
+Tells what failed, not how to fix it.
+
+✅ **Good Design (Actionable Guidance):**
+```
+"Error: Query too broad - returned 1,247 results. Try adding filters:
+use 'team:marketing' to filter by team, or 'status:active'
+to filter by status. Or use limit=50 with offset for pagination."
+
+"Error: Date format invalid. Expected YYYY-MM-DD (e.g., '2024-01-15'),
+received '01/15/2024'. Please use ISO format."
+
+"Error: Missing required field 'project_id'. To find project IDs,
+use list_projects(team='your-team') first."
+```
+Each error teaches correct usage patterns.
+
+**Guidelines:**
+- Explain what's wrong and why
+- Suggest specific fixes or alternative parameters
+- Reference other tools when needed ("use X tool to find Y first")
+- Include examples of correct usage in error messages
+- Guide agents through multi-step corrections
+- Make errors educational, not just diagnostic
+
+### 4. Follow Natural Task Subdivisions
+
+**The Problem:**
+Tool organization that mirrors API structure doesn't match how agents think about tasks.
+
+**The Solution:**
+Organize and name tools around natural task categories that align with agent reasoning.
+
+**Examples:**
+
+❌ **Poor Design (API Structure):**
+```
+api_users_get(id)
+api_users_list(filters)
+api_users_create(data)
+api_projects_get(id)
+api_projects_list(filters)
+```
+Tool names reflect internal API, not user tasks.
+
+✅ **Good Design (Task-Oriented):**
+```
+search_users(query, team, status)
+get_user_details(user_id)
+create_user_account(name, email, team)
+
+find_projects(name, status, team)
+get_project_info(project_id)
+create_project(name, team, deadline)
+```
+Tool names reflect what agents want to accomplish.
+
+**Guidelines:**
+- Use action verbs that describe tasks: search, find, create, update, analyze
+- Group related tools with consistent prefixes for discoverability
+- Include service prefix to prevent conflicts: `slack_send_message` not `send_message`
+- Name tools how humans would describe the task
+- Use consistent naming patterns within your server
+
+### 5. Use Evaluation-Driven Development
+
+**The Problem:**
+Building without testing against realistic agent use cases leads to tools that seem correct but fail in practice.
+
+**The Solution:**
+Create evaluation scenarios early and iterate based on actual agent performance.
+
+**Examples:**
+
+**Evaluation-First Workflow:**
+1. **Before Implementation**: Define 10 realistic questions agents should answer
+2. **Prototype Quickly**: Build minimal tool set to attempt evaluations
+3. **Run Evaluations**: See where agents struggle
+4. **Iterate**: Improve tools based on agent feedback
+5. **Repeat**: Until agents successfully complete 80%+ of evaluations
+
+**Common Discoveries from Evaluations:**
+- Agents couldn't find information → Add search/filter tools
+- Agents made too many calls → Consolidate into workflow tools
+- Agents got confused → Improve tool descriptions and error messages
+- Agents ran out of context → Reduce response verbosity
+- Agents used tools incorrectly → Add actionable error guidance
+
+**Guidelines:**
+- Write evaluations before implementing all tools
+- Use realistic, complex questions requiring multiple tool calls
+- Let agent failures drive tool design decisions
+- Iterate based on evaluation results, not assumptions
+- Aim for 80%+ agent success rate on evaluations
+
+---
+
+## Applying These Principles: A Case Study
+
+**Scenario:** Building an MCP server for a project management API.
+
+### ❌ API Wrapper Approach (Poor)
+
+```python
+@mcp.tool()
+async def get_task(task_id: str):
+    """Get a task by ID."""
+    return api.tasks.get(task_id)
+
+@mcp.tool()
+async def list_tasks(project_id: str):
+    """List all tasks in a project."""
+    return api.tasks.list(project_id)
+
+@mcp.tool()
+async def get_user(user_id: str):
+    """Get user by ID."""
+    return api.users.get(user_id)
+
+@mcp.tool()
+async def update_task_status(task_id: str, status: str):
+    """Update task status."""
+    return api.tasks.update(task_id, {"status": status})
+```
+
+**Problems:**
+- Too granular - agent needs many calls for simple workflows
+- Returns all fields - wastes context on unnecessary data
+- No guidance on valid statuses or error handling
+- Agent must know IDs before making calls
+- Mirrors API structure, not task structure
+
+### ✅ Agent-Centric Approach (Good)
+
+```python
+@mcp.tool()
+async def search_tasks(
+    query: str,
+    project: Optional[str] = None,
+    status: Optional[str] = None,
+    assignee: Optional[str] = None,
+    limit: int = 20,
+    response_format: str = "markdown"
+) -> str:
+    """Search for tasks across projects with flexible filtering.
+
+    Finds tasks by name, description, or tags. Returns concise results
+    by default - use response_format='json' for full data.
+
+    Common workflows:
+    - Find all bugs: search_tasks(query="bug", status="open")
+    - Find your tasks: search_tasks(assignee="your-name")
+    - Find by project: search_tasks(project="website-redesign")
+
+    Error guidance:
+    - If too many results: Add more filters or use limit parameter
+    - If no results: Try broader query or check project name spelling
+    - To find project names: Use list_projects() first
+    """
+    # Implementation with:
+    # - Concise markdown by default
+    # - Full JSON if requested
+    # - Actionable errors with examples
+    # - Character limit enforcement
+
+@mcp.tool()
+async def complete_task(
+    task_id: str,
+    completion_note: Optional[str] = None,
+    notify_team: bool = True
+) -> str:
+    """Mark a task complete and optionally notify the team.
+
+    This is a workflow tool that:
+    1. Validates task can be completed (not blocked, has assignee)
+    2. Updates task status to 'completed'
+    3. Adds completion note to task history
+    4. Sends notifications to team members (if notify_team=True)
+    5. Updates project progress metrics
+
+    Returns: Success message with task name and updated project status
+
+    Error guidance:
+    - "Task is blocked": Lists blocking tasks with IDs
+    - "Task has no assignee": Suggests using assign_task(task_id, user)
+    - "Invalid task_id": Suggests using search_tasks() to find task
+    """
+    # Implementation handles entire workflow
+
+@mcp.tool()
+async def get_project_status(
+    project_name: str,
+    include_tasks: bool = False
+) -> str:
+    """Get project overview with completion metrics.
+
+    Returns concise summary by default:
+    - Total tasks, completed, in-progress, blocked
+    - Recent activity
+    - Team members
+    - Due date and status
+
+    Use include_tasks=True to also list all tasks (uses more context).
+
+    Error guidance:
+    - "Project not found": Lists similar project names
+    - "Access denied": Explains permission requirements
+    """
+    # Returns high-signal summary
+```
+
+**Improvements:**
+- **Workflow-oriented**: `complete_task` handles entire workflow, not just status update
+- **Context-efficient**: Concise by default, detailed on request
+- **Actionable errors**: Guides agents to correct usage
+- **Natural naming**: Search, complete, get_status (task-oriented, not API-oriented)
+- **Flexible search**: One tool handles multiple search scenarios
+- **Human-readable**: Uses project names, not just IDs
+
+---
+
+## Pre-Implementation Checklist
+
+Before writing any code, ensure you understand:
+
+- [ ] What workflows will agents actually need to accomplish?
+- [ ] What's the minimum information needed for each workflow?
+- [ ] What errors will agents encounter and how can I guide them?
+- [ ] How can I consolidate related operations into single tools?
+- [ ] What evaluation scenarios will test if this works?
+- [ ] Are tool names task-oriented or API-oriented?
+- [ ] Do tools default to concise responses?
+- [ ] Do errors teach correct usage?
+
+---
+
+## Common Anti-Patterns to Avoid
+
+### Anti-Pattern 1: CRUD Over Everything
+Creating separate create/read/update/delete tools for every resource.
+
+**Instead:** Create workflow tools that combine operations intelligently.
+
+### Anti-Pattern 2: The Everything Tool
+One tool that takes 15+ parameters and tries to do everything.
+
+**Instead:** Multiple focused tools, each solving one clear workflow.
+
+### Anti-Pattern 3: ID-Only Interfaces
+Requiring agents to have IDs before calling any tools.
+
+**Instead:** Search/find tools that work with human-readable names.
+
+### Anti-Pattern 4: Silent Truncation
+Cutting off results without telling the agent.
+
+**Instead:** Clear truncation messages with guidance on filtering.
+
+### Anti-Pattern 5: Error Code Responses
+Returning `ERR_401`, `ERR_404` without explanation.
+
+**Instead:** Actionable error messages with specific next steps.
+
+---
+
+## Next Steps
+
+After understanding these principles:
+
+1. **Review Real Examples**: Look at well-designed MCP servers in the wild
+2. **Start Planning**: Create your implementation plan with these principles in mind
+3. **Load Workflow Guide**: See [workflow.md](./workflow.md) for step-by-step implementation
+4. **Reference Best Practices**: Use [mcp_best_practices.md](./mcp_best_practices.md) for technical details
+5. **Create Evaluations Early**: Don't wait until implementation is complete
+
+---
+
+**Remember:** Agents are your users. Design for their constraints, optimize for their workflows, and guide them to success through every interaction.