python-to-typescript-assistant

🐍➡️📘 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

⚡ Quick Start

Get started immediately with npx - no installation required:

# Run the server with npx
npx python-to-typescript-porting-mcp-server

Then configure your MCP client (like Claude Desktop) to use the server:

{
  "mcpServers": {
    "python-to-typescript-porting": {
      "command": "npx",
      "args": ["python-to-typescript-porting-mcp-server"],
      "env": {}
    }
  }
}

🚀 Features

🛠️ Tools

1. 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

2. 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.)

3. 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

4. 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

5. validation-strategy - Testing and validation approaches for conversions

   • Type safety validation strategies
   • Behavioral equivalence testing
   • Performance validation techniques

📚 Resources

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

💬 Prompts

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

📦 Installation

Installing via Smithery

To install python-to-typescript-assistant for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @glassBead-tc/python-to-typescript-assistant --client claude

Prerequisites

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

Quick Start with NPX (Recommended)

The easiest way to use the server is via npx - no installation required:

# Run directly with npx
npx python-to-typescript-porting-mcp-server

# Or use the shorter command alias
npx py-to-ts-server

Install from NPM

# Install globally
npm install -g python-to-typescript-porting-mcp-server

# Run the server
py-to-ts-server

Build from Source

For development or customization:

# Clone the repository
git clone https://github.com/glassBead-tc/python-to-typescript-assistant.git
cd python-to-typescript-assistant

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
npm start

🔧 Configuration

Claude Desktop

Option 1: Using NPX (Recommended)

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "python-to-typescript-porting": {
      "command": "npx",
      "args": ["python-to-typescript-porting-mcp-server"],
      "env": {}
    }
  }
}

Option 2: Using Global Installation

If you installed globally with npm:

{
  "mcpServers": {
    "python-to-typescript-porting": {
      "command": "py-to-ts-server",
      "env": {}
    }
  }
}

Option 3: Using Local Build

If you built from source:

{
  "mcpServers": {
    "python-to-typescript-porting": {
      "command": "node",
      "args": ["/path/to/python-to-typescript-assistant/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. Use the appropriate command from the options above based on your installation method.

🐳 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

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 .

🎯 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

Quick Testing with NPX

# Test the server directly
npx python-to-typescript-porting-mcp-server

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

Development Testing

For development and customization:

# Run the development server with watch mode
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

Manual Testing

1. Strategy Analysis: Test with a sample Python project structure
2. Type Mapping: Try complex Python type annotations
3. Library Lookup: Test common Python libraries
4. 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 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

• MCP Documentation
• TypeScript Handbook
• Sequential Thinking MCP Patterns

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