gh-linus-mcmanamey-unify-2-1-plugin/skills/mcp-code-execution.md

name, description

name	description
mcp-code-execution	Context-efficient MCP integration using code execution patterns. Use when building agents that interact with MCP servers, need to manage large tool sets (50+ tools), process large datasets through tools, or require multi-step workflows with intermediate results. Enables progressive tool loading, data filtering before context, and reusable skill persistence. (project, gitignored)

MCP Code Execution

Implement context-efficient MCP integrations using code execution patterns instead of direct tool calls.

When to Use This Skill

Load this skill when you need to:

• Work with MCP servers that expose 50+ tools (avoid context pollution)
• Process large datasets through MCP tools (filter before returning to context)
• Build multi-step workflows with intermediate results
• Create reusable skill functions that persist across sessions
• Progressively discover and load only needed tools
• Achieve 98%+ context savings on MCP-heavy workflows

Core Concept

Present MCP servers as code APIs on a filesystem. Load tool definitions on-demand, process data in execution environment, only return filtered results to context.

Context Efficiency:

• Before: 150K tokens (all tool definitions + intermediate results)
• After: 2K tokens (only used tools + filtered results)
• Savings: 98.7%

Quick Start

1. Generate Tool API from MCP Server

python scripts/mcp_generator.py --server-config servers.json --output ./mcp_tools

Creates a filesystem API:

mcp_tools/
├── google_drive/
│   ├── get_document.py
│   └── list_files.py
├── salesforce/
│   ├── update_record.py
│   └── query.py
└── client.py  # MCP client wrapper

2. Use Context-Efficient Patterns

import mcp_tools.google_drive as gdrive
import mcp_tools.salesforce as sf

# Filter data before returning to context
sheet = await gdrive.get_sheet("abc123")
pending = [r for r in sheet if r["Status"] == "pending"]
print(f"Found {len(pending)} pending orders")  # Only summary in context

# Chain operations without intermediate context pollution
doc = await gdrive.get_document("xyz789")
await sf.update_record("Lead", "00Q123", {"Notes": doc["content"]})
print("Document attached to lead")  # Only confirmation in context

3. Discover Tools Progressively

from scripts.tool_discovery import discover_tools, load_tool_definition

# List available servers
servers = discover_tools("./mcp_tools")
# ['google_drive', 'salesforce']

# Load only needed tool definitions
tool = load_tool_definition("./mcp_tools/google_drive/get_document.py")

Multi-Agent Workflow

For complex tasks, delegate to specialized sub-agents:

1. Discovery Agent: Explores available tools, returns relevant paths
2. Execution Agent: Writes and runs context-efficient code
3. Filtering Agent: Processes results, returns minimal context

Documentation Structure

This skill has comprehensive documentation organized by topic:

Quick Reference

• QUICK_START.md - 5-minute getting started guide
  • Installation and setup
  • First MCP integration
  • Common patterns
  • Troubleshooting

Core Concepts

• SKILL.md - Complete skill specification
  • Context optimization techniques
  • Tool discovery strategies
  • Privacy and security
  • Advanced patterns (aggregation, joins, polling, batching)

Integration Guide

• ADDING_MCP_SERVERS.md - How to add new MCP servers
  • Server configuration
  • Tool generation
  • Custom adapters
  • Testing and validation

Supporting Files

• examples/ - Working code examples
• references/ - Pattern libraries and references
• scripts/ - Helper utilities (mcp_generator.py, tool_discovery.py)
• mcp_configs/ - Server configuration templates

Common Use Cases

1. Azure DevOps MCP (Current Project)

Without this approach:

• Load ADO MCP → 50+ tools → 10,000-25,000 tokens

With this approach:

from scripts.ado_pr_helper import ADOHelper

ado = ADOHelper()
pr = ado.get_pr(5860)
print(f"PR {pr['title']}: {pr['mergeStatus']}")
# Only 500-2,000 tokens

2. Data Pipeline Integration

# Fetch from Google Sheets, process, push to Salesforce
sheet = await gdrive.get_sheet("pipeline_data")
validated = [r for r in sheet if validate_record(r)]
for record in validated:
    await sf.create_record("Lead", record)
print(f"Processed {len(validated)} records")

3. Multi-Source Aggregation

# Aggregate from multiple sources without context bloat
github_issues = await github.list_issues(repo="project")
jira_tickets = await jira.search("project = PROJ")
combined = merge_and_dedupe(github_issues, jira_tickets)
print(f"Total issues: {len(combined)}")

Tool Discovery Strategies

Filesystem Exploration

List ./mcp_tools/ directory, read specific tool files as needed.

Search-Based Discovery

from scripts.tool_discovery import search_tools

tools = search_tools("./mcp_tools", query="salesforce lead", detail="name_only")
# Returns: ['salesforce/query.py', 'salesforce/update_record.py']

Lazy Loading

Only read full tool definitions when about to use them.

Persisting Skills

Save working code as reusable functions:

# ./skills/extract_pending_orders.py
async def extract_pending_orders(sheet_id: str):
    sheet = await gdrive.get_sheet(sheet_id)
    return [r for r in sheet if r["Status"] == "pending"]

Privacy & Security

Data processed in execution environment stays there by default. Only explicitly logged/returned values enter context.

Integration with Project

With Azure DevOps

• azure-devops skill uses this pattern via ado_pr_helper.py
• Avoids loading 50+ ADO MCP tools
• Returns filtered PR/work item summaries

With Git Manager

• PR operations use context-efficient ADO helpers
• Work item linking without full MCP tool loading

With Documentation

• Potential future: Wiki operations via MCP

Best Practices

DO

• ✅ Generate filesystem APIs for MCP servers
• ✅ Filter data before returning to context
• ✅ Use progressive tool discovery
• ✅ Persist working code as reusable skills
• ✅ Return summaries instead of full datasets
• ✅ Chain operations to minimize intermediate context

DON'T

• ❌ Load all MCP tools into context upfront
• ❌ Return large datasets to context unfiltered
• ❌ Re-discover tools repeatedly (cache discovery)
• ❌ Mix tool definitions with execution code
• ❌ Expose sensitive data in print statements

Performance Metrics

Metric	Direct MCP Tools	Code Execution Pattern	Improvement
Context Usage	150K tokens	2K tokens	98.7% reduction
Initial Load	10K-25K tokens	500 tokens	95% reduction
Result Size	50K tokens	1K tokens	98% reduction
Workflow Speed	Slow (context overhead)	Fast (in-process)	5-10x faster

Quick Command Reference

Generate MCP Tools

python scripts/mcp_generator.py --server-config servers.json --output ./mcp_tools

Discover Available Tools

python scripts/tool_discovery.py --mcp-dir ./mcp_tools

Test Tool Integration

python scripts/test_mcp_tool.py google_drive/get_document

Troubleshooting

Issue: Tool Generation Failed

• Verify MCP server is running
• Check server configuration in servers.json
• Review MCP client connection

Issue: Import Errors

• Ensure mcp_tools/ is in Python path
• Check client.py is generated correctly
• Verify all dependencies installed

Issue: Context Still Large

• Review what data is being returned
• Add more aggressive filtering
• Use summary statistics instead of raw data

Future Enhancements

Planned additions:

• Auto-generate README for each MCP server
• Tool usage analytics and recommendations
• Cached tool discovery
• Multi-MCP orchestration patterns

Getting Started

1. New to MCP Code Execution? → Read QUICK_START.md
2. Adding a new MCP server? → Read ADDING_MCP_SERVERS.md
3. Need advanced patterns? → Read SKILL.md sections on aggregation, joins, polling
4. Want examples? → Browse examples/ directory

Related Skills

• azure-devops - Uses this pattern for ADO MCP integration
• multi-agent-orchestration - Delegates MCP work to specialized agents
• skill-creator - Create reusable MCP integration skills

---

Created: 2025-11-09 Version: 1.0 Documentation: 15,411 lines total (SKILL.md: 3,550, ADDING_MCP_SERVERS.md: 7,667, QUICK_START.md: 4,194) Maintainer: AI Agent Team Status: Production Ready