MCP-Proxy Workspace

English | 简体中文

MCP-Proxy Workspace

A comprehensive Rust workspace implementing MCP (Model Context Protocol) proxy system with multiple services including document parsing, voice transcription, and protocol conversion.

Workspace Members

Quick Start

Prerequisites

• Rust: 1.70 or later (recommended 1.75+)
• Python: 3.8+ (for document-parser and voice-cli TTS)
• uv: Python package manager (install via curl -LsSf https://astral.sh/uv/install.sh | sh)

Installation

Method 1: Pre-built Binaries (Recommended)

Using installation script (Linux/macOS):

# Install mcp-proxy
curl --proto '=https' --tlsv1.2 -sSf https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/mcp-stdio-proxy-installer.sh | sh

# Install document-parser
curl --proto '=https' --tlsv1.2 -sSf https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/document-parser-installer.sh | sh

# Install voice-cli
curl --proto '=https' --tlsv1.2 -sSf https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/voice-cli-installer.sh | sh

Using installation script (Windows PowerShell):

# Install mcp-proxy
irm https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/mcp-stdio-proxy-installer.ps1 | iex

# Install document-parser
irm https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/document-parser-installer.ps1 | iex

# Install voice-cli
irm https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/voice-cli-installer.ps1 | iex

Download from GitHub Releases: Visit GitHub Releases to download binaries for your platform.

Supported platforms:

• Linux x86_64
• Linux ARM64
• macOS Intel (x86_64)
• macOS Apple Silicon (ARM64)
• Windows x86_64

Method 2: cargo install

cargo install mcp-stdio-proxy

Method 3: Build from Source

# Clone repository
git clone https://github.com/nuwax-ai/mcp-proxy.git
cd mcp-proxy

# Build all workspace members
cargo build --release

# Or build specific crates
cargo build -p mcp-proxy
cargo build -p document-parser
cargo build -p voice-cli

MCP Proxy (mcp-stdio-proxy)

The main proxy service that converts SSE/Streamable HTTP to stdio protocol.

# Install from source
cargo install --path ./mcp-proxy

# Start the proxy server
mcp-proxy

# Convert remote MCP service to stdio
mcp-proxy convert https://example.com/mcp/sse

# Check service status
mcp-proxy check https://example.com/mcp/sse

# Detect protocol type
mcp-proxy detect https://example.com/mcp

See: mcp-proxy/README.md for detailed documentation.

Document Parser

High-performance document parsing service supporting PDF, Word, Excel, and PowerPoint.

cd document-parser

# Initialize Python environment (first time)
document-parser uv-init

# Check environment status
document-parser check

# Start HTTP server
document-parser server

See: document-parser/README.md for detailed documentation.

Voice CLI

Speech-to-text HTTP service with Whisper model support.

cd voice-cli

# Initialize server configuration
voice-cli server init

# Run voice server
voice-cli server run

# List Whisper models
voice-cli model list

# Download model
voice-cli model download tiny

See: voice-cli/README.md for detailed documentation.

Architecture

Core Services

1. MCP Proxy System

• mcp-common: Shared configuration types and utilities
• mcp-sse-proxy: SSE protocol support (rmcp 0.10)
• mcp-streamable-proxy: Streamable HTTP protocol support (rmcp 0.12)
• mcp-stdio-proxy: Main CLI tool for protocol conversion

Features:

• Multi-protocol support: SSE, Streamable HTTP, stdio
• Dynamic plugin loading
• Protocol auto-detection and conversion
• OpenTelemetry integration with OTLP
• Background health checks

2. Document Parser

Features:

• Multi-format support: PDF (MinerU), Word/Excel/PowerPoint (MarkItDown)
• GPU acceleration via CUDA/sglang (optional)
• Python environment management with uv
• HTTP API with OpenAPI documentation
• OSS integration for cloud storage

3. Voice CLI

Features:

• Whisper model integration (tiny/base/small/medium/large)
• Multi-format audio support (MP3, WAV, FLAC, M4A, etc.)
• Apalis-based async task queue with SQLite persistence
• FFmpeg integration for metadata extraction
• TTS service (TODO - currently has issues)

4. Utility Libraries

• oss-client: Alibaba Cloud OSS client with unified interface
• fastembed: Text embedding HTTP service using FastEmbed

Development

Build Commands

# Build all workspace crates
cargo build

# Build specific crate
cargo build -p mcp-proxy

# Build in release mode
cargo build --release

# Run tests for all crates
cargo test

# Run tests for specific crate
cargo test -p mcp-proxy

# Run clippy for linting
cargo clippy --all-targets --all-features

# Format code
cargo fmt

Cross-Platform Building (Docker)

# Build document-parser for Linux x86_64
make build-document-parser-x86_64

# Build document-parser for Linux ARM64
make build-document-parser-arm64

# Build voice-cli for Linux x86_64
make build-voice-cli-x86_64

# Build all components for x86_64
make build-all-x86_64

# Build Docker runtime image
make build-image

# Run Docker container
make run

Code Style

• Line length: 100 characters
• 4-space indentation (no tabs)
• Use dashmap for concurrent hashmaps instead of Arc<RwLock<HashMap>>
• Follow KISS and SOLID principles
• "Fail fast" error handling with anyhow::Context

Documentation

• CLAUDE.md - Development guide for contributors
• mcp-proxy/README.md - MCP Proxy documentation
• document-parser/README.md - Document Parser documentation
• voice-cli/README.md - Voice CLI documentation
• oss-client/README.md - OSS Client documentation

License

This project is dual-licensed under MIT OR Apache-2.0.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

• GitHub Repository: https://github.com/nuwax-ai/mcp-proxy
• Issue Tracker: https://github.com/nuwax-ai/mcp-proxy/issues
• Discussions: https://github.com/nuwax-ai/mcp-proxy/discussions

Related Resources

• MCP Official Documentation
• rmcp - Rust MCP Implementation
• MCP Servers List