Skip to content

Latest commit

 

History

History
237 lines (162 loc) · 6.17 KB

README.md

File metadata and controls

237 lines (162 loc) · 6.17 KB

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.

License: MIT OR Apache-2.0 Rust

Workspace Members

Crate Version Description
mcp-common 0.1.5 Shared types and utilities for MCP proxy components
mcp-sse-proxy 0.1.5 SSE (Server-Sent Events) proxy implementation using rmcp 0.10
mcp-streamable-proxy 0.1.5 Streamable HTTP proxy implementation using rmcp 0.12
mcp-stdio-proxy 0.1.18 Main MCP proxy server with CLI tool for protocol conversion
document-parser 0.1.0 High-performance multi-format document parsing service
voice-cli 0.1.0 Speech-to-text HTTP service with Whisper model support
oss-client 0.1.0 Lightweight Alibaba Cloud OSS client library
fastembed 0.1.0 Text embedding HTTP service using FastEmbed

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

# Clone the 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

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.

Related Resources