clawdbot-workspace/skill-updates/mcp-learnings.md

MCP Skills Inventory & Updates Needed

What We've Built

• 30 MCP servers (TypeScript) across 10 categories
• 11 GHL MCP Apps with structuredContent UI
• ~240 total tools
• Full deployment configs (Docker, Railway, Vercel)
• Marketing assets (diagrams, comparisons, landing pages)

Skills We Have

1. mcp-apps-official — Building MCP Apps with UI (located in workspace)
2. mcporter — Using/calling MCP servers as a client
3. skill-creator — Creating AgentSkills

Skills We NEED (gaps identified)

1. MCP Server Development (NEW)

Why: We have no skill for building TypeScript MCP servers What it should cover:

• Project structure (src/, dist/, package.json, tsconfig.json)
• Tool definitions with proper JSON schema
• Server.ts setup with MCP SDK
• Error handling patterns
• Resource definitions
• Prompts (if applicable)
• Testing approach
• Build/compile process
• Common pitfalls we hit 30 times

2. MCP Server + App Integration (NEW)

Why: The workflow of building server tools + apps together isn't documented What it should cover:

• When to use apps vs just tools
• Passing tool results to apps
• structuredContent patterns we discovered
• App-tool coordination
• UI rendering best practices

3. MCP Deployment & Distribution (NEW)

Why: We built Docker, Railway, Vercel configs 30 times What it should cover:

• Docker containerization
• Railway.json patterns
• Environment variable management
• README templates
• GitHub repo structure
• npm publishing (if applicable)

Skills to UPDATE

mcporter skill

Current state: Focuses on calling MCP servers What to add:

• Examples from our 30 servers
• Common tool patterns
• Better error handling examples

mcp-apps-official skill

Current state: Good foundation What to add:

• Our 11 app examples as reference
• structuredContent patterns we used
• Common UI components (grids, cards, timelines)
• Best practices we discovered

Patterns We Learned (should go in new skills)

TypeScript MCP Server Patterns

1. Tool naming: verb_noun format (get_contacts, create_campaign)
2. Schema validation: Always use Zod for input validation
3. Error wrapping: Try-catch with descriptive error messages
4. Response format: Consistent { success, data, error } pattern
5. Auth handling: Environment variables, never hardcode
6. Rate limiting: Document in tool descriptions
7. Pagination: When to use it, how to expose it
8. Type safety: Leverage TypeScript fully, avoid any

MCP App UI Patterns

1. Grid layouts: Contact grids, pipeline boards
2. Card components: Opportunity cards, invoice previews
3. Timeline views: Activity feeds, contact history
4. Stats dashboards: Campaign performance, agent metrics
5. Forms: Quick actions embedded in UI
6. Structured content: HTML-based, renders in Claude Desktop

Integration Patterns

1. Multi-app servers: When one server should have multiple apps
2. Tool → App flow: Call tool, render result in app UI
3. State management: Apps are stateless, tools handle data
4. Error states: How to show errors in app UI

Deployment Patterns

1. Docker: Multi-stage builds, environment injection
2. Railway: railway.json with start command + env template
3. Vercel: For web-based MCP servers (if applicable)
4. GitHub: README with setup, .env.example, gitignore

Action Plan

1. Create mcp-server-development skill (comprehensive)
2. Create mcp-apps-integration skill (server + apps workflow)
3. Create mcp-deployment skill (Docker/Railway/GitHub)
4. Update mcp-apps-official with our 11 app examples
5. Update mcporter with our server examples