feat: Add context-aware proxy mode with template support for MCP server configurations

[xizhibei]

Summary

This feature introduces context-aware proxy mode, allowing MCP server configurations to use dynamic templates with project-specific context variables. This enables intelligent server configurations that adapt to different development environments, teams, and projects.

Key Changes

🎯 Core Features

• Template Engine Integration: Handlebars-based template processing for MCP server configurations
• Context Collection: Automatic gathering of project, user, environment, and git context
• Dynamic Configuration: Server configurations can now use variables like {project.name}, {user.username}, {environment}, etc.
• Conditional Server Enablement: Servers can be enabled/disabled based on environment or context conditions
• Template Caching: Performance optimization with context-aware template caching

📁 New Files Added

• src/types/context.ts - Context data type definitions
• src/context/ - Context collection and management services
• src/template/ - Template processing engine with Handlebars integration
• mcp.json.example - Comprehensive examples showcasing template usage

🔧 Configuration Updates

• Project Context: projectId, environment, team, custom variables
• Template Settings: Validation, failure mode, caching configuration
• Environment Integration: Automatic environment variable collection with prefix filtering
• Git Information: Branch, commit, repository details for context awareness

🏗️ Architecture Enhancements

• Proxy Transport: Enhanced to pass project configuration for context enrichment
• Config Manager: Extended with template processing capabilities
• Session Management: Added context data to session types for persistence

Template Examples

{
  "mcpTemplates": {
    "project-serena": {
      "command": "npx",
      "args": ["-y", "serena", "{project.path}"],
      "env": {
        "PROJECT_ID": "{project.custom.projectId}",
        "SESSION_ID": "{context.sessionId}",
        "GIT_BRANCH": "{project.git.branch?:main}"
      },
      "tags": ["filesystem", "search"]
    },
    "conditional-server": {
      "command": "node",
      "args": ["{project.path}/server.js"],
      "env": {
        "NODE_ENV": "{project.environment}",
        "DEBUG": "{?project.environment=development:true}"
      },
      "disabled": "{?project.environment=production}"
    }
  }
}

Available Template Variables

• Project: {project.path}, {project.name}, {project.environment}, {project.custom.*}
• User: {user.username}, {user.email}, {user.home}
• Git: {project.git.branch}, {project.git.commit}, {project.git.repository}
• Environment: {environment.variables.*}, {context.timestamp}
• Functions: |upper, |lower, |truncate(10), |replace(from,to), |default(value)

Testing

• ✅ Comprehensive unit tests for template processing and context collection
• ✅ Integration tests for proxy transport with context enrichment
• ✅ Error handling validation with graceful failure modes
• ✅ Performance tests for template caching and context processing
• ✅ End-to-end tests for complete template workflow

Breaking Changes

• None - this is a purely additive feature that maintains backward compatibility

Migration Guide

1. Add "context" section to your .1mcprc configuration file
2. Define project-specific variables like projectId, environment, team
3. Create mcpTemplates section in your MCP configuration
4. Use template variables in server commands, arguments, and environment variables
5. Restart 1MCP proxy to enable context-aware processing

Benefits

• Environment-Aware: Servers automatically adapt to development/staging/production environments
• Team Configurations: Different teams can have customized server setups
• Dynamic Configuration: No more hardcoded paths or environment-specific configs
• Centralized Context: Single source of truth for project metadata
• Template Reusability: Share template configurations across projects and teams