🐍➡️📘 Python-to-TypeScript Porting MCP Server

A comprehensive Model Context Protocol (MCP) server that provides systematic tools and references for porting Python code to TypeScript. This server combines model enhancement capabilities with practical porting resources to address the challenges identified in Python-to-TypeScript migration projects.

🎯 Purpose

Based on research showing that current AI translation approaches achieve only a 47% success rate for real-world Python-to-TypeScript conversions, this MCP server provides:

Systematic thinking frameworks for breaking down complex porting tasks
Type analysis tools for understanding Python types and suggesting TypeScript equivalents
Library mapping database with migration guidance and alternatives
Pattern recognition for converting Python idioms to TypeScript best practices
Validation strategies for ensuring porting correctness
Quality references with TypeScript best practices for Python developers

🚀 Features

🛠️ Tools

porting-strategy - Systematic framework for analyzing and planning porting projects
- Strategic analysis with complexity assessment
- Risk evaluation and phased migration planning
- Dependency graph analysis and critical path identification
- Effort estimation and timeline recommendations
type-analysis - Python type analysis with TypeScript mapping recommendations
- Comprehensive type system mapping (primitives, collections, generics, unions)
- Migration complexity assessment
- Runtime considerations and testing approaches
- Library-specific type mappings (datetime, pathlib, dataclasses, etc.)
library-mapping - Find TypeScript/JavaScript equivalents for Python libraries
- Extensive library database with confidence ratings
- Installation commands and API difference notes
- Migration complexity assessment
- Alternative approaches when no direct equivalent exists
pattern-mapping - Convert Python language patterns to TypeScript equivalents
- List/dict comprehensions → Array methods
- Context managers → try/finally patterns
- Multiple assignment → destructuring
- Code examples with caveats and best practices
validation-strategy - Testing and validation approaches for conversions
- Type safety validation strategies
- Behavioral equivalence testing
- Performance validation techniques

📚 Resources

typescript://best-practices - TypeScript best practices for Python developers
typescript://type-system - Comprehensive TypeScript type system guide
guides://methodology - Step-by-step porting methodology
db://libraries - Quick reference library mapping database

💬 Prompts

analyze-python-file - Generate prompts for analyzing Python code complexity
review-typescript-conversion - Generate prompts for reviewing converted code

📦 Installation

Prerequisites

Node.js 18+ and npm
TypeScript 5.0+
An MCP-compatible client (like Claude Desktop)

Build from Source

# Clone the repository
git clone <repository-url>
cd python-to-typescript

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
npm start

🔧 Configuration

Claude Desktop

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "python-to-typescript-porting": {
      "command": "node",
      "args": ["/path/to/python-to-typescript/dist/index.js"],
      "env": {}
    }
  }
}

Other MCP Clients

The server uses stdio transport and can be integrated with any MCP-compatible client that supports subprocess communication.

🐳 Docker Support

The project includes comprehensive Docker support for both development and production environments.

Quick Start with Docker

# Build and run with Docker Compose
npm run compose:up

# View logs
npm run compose:logs

# Stop the server
npm run compose:down

Development with Docker

# Start development environment with hot reloading
npm run compose:dev

# View development logs
docker-compose logs -f mcp-server-dev

Available Docker Scripts

Script	Description
`npm run docker:build`	Build production Docker image
`npm run docker:build-dev`	Build development Docker image
`npm run compose:up`	Start production services
`npm run compose:dev`	Start development services
`npm run compose:down`	Stop all services
`npm run compose:logs`	View service logs

Docker Features

Multi-stage builds for optimized production images
Development environment with hot reloading
Health checks and resource limits
Non-root user for security
Alpine Linux base for minimal footprint

For detailed Docker documentation, see DOCKER.md.

🎯 Usage Examples

Analyzing a Python Project

// Use the porting-strategy tool
{
  "projectId": "my-flask-app",
  "projectName": "Flask API Server",
  "stage": "analysis",
  "components": [
    {
      "name": "app.py",
      "type": "module",
      "complexity": "medium",
      "dependencies": ["flask", "sqlalchemy"],
      "challenges": ["Dynamic routing", "ORM relationships"],
      "portingApproach": "Convert to Express.js + TypeORM",
      "estimatedEffort": 16
    }
  ]
}

Analyzing Python Types

// Use the type-analysis tool
{
  "pythonType": "Dict[str, Optional[List[User]]]",
  "context": "API response format"
}

Finding Library Equivalents

// Use the library-mapping tool
{
  "pythonLibrary": "requests"
}

Converting Python Patterns

// Use the pattern-mapping tool
{
  "pattern": "list comprehension"
}

🧠 Model Enhancement Approach

This server implements "model enhancement" patterns inspired by the Sequential Thinking approach, providing:

Systematic problem decomposition for complex porting tasks
Context maintenance across long migration operations
Decision framework tools for evaluating migration strategies
Progressive refinement of porting approaches
Risk assessment and mitigation planning

📊 Research Foundation

The server addresses specific challenges identified in Python-to-TypeScript migration research:

Type system mismatch - Python's dynamic typing vs TypeScript's static types
Library ecosystem gaps - Missing TypeScript equivalents for Python libraries
Pattern translation - Converting Python idioms to TypeScript best practices
Validation complexity - Ensuring behavioral equivalence after migration
Strategic planning - Systematic approaches to large-scale migrations

🏗️ Architecture

src/
├── index.ts              # Main server entry point
├── tools/                # MCP tools for analysis and mapping
│   ├── porting-strategy.ts   # Strategic planning framework
│   ├── type-analysis.ts      # Type system analysis
│   ├── library-mapping.ts    # Library equivalents database
│   ├── pattern-mapping.ts    # Pattern conversion guide
│   └── validation.ts         # Testing strategies
├── resources/            # Reference materials and guides
│   ├── typescript-references.ts
│   ├── porting-guides.ts
│   └── library-database.ts
└── prompts/             # Template prompts for common tasks
    └── porting-prompts.ts

🔬 Testing

The server includes comprehensive testing strategies:

# Run the development server
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

Manual Testing

Strategy Analysis: Test with a sample Python project structure
Type Mapping: Try complex Python type annotations
Library Lookup: Test common Python libraries
Pattern Conversion: Test Python idioms and patterns

🤝 Contributing

Contributions are welcome! Key areas for improvement:

Extended library mappings - Add more Python-to-TypeScript library equivalents
Pattern database - Expand Python pattern recognition and conversion
Validation tools - Improve testing and validation strategies
Type inference - Enhance Python type analysis capabilities
Performance optimization - Improve server response times

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Inspired by research from Anthropic's Model Context Protocol
Sequential Thinking patterns from the MCP 101 series
Python-to-TypeScript migration research and real-world case studies
The TypeScript and Python communities for best practices and tooling

📖 Related Resources

Built with ❤️ for the Python and TypeScript communities # python-to-typescript-assistant