qwen3-mcp-server: Instructions file for Codex

AGENTS.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that provides standardized access to the Qwen3-30B model for integration with Warp and other MCP-compatible clients. The server supports three hosting methods: Ollama (recommended), local Transformers, and HTTP API endpoints.

Architecture

Core Components

• src/main.py: Entry point with CLI argument parsing and server lifecycle management
• src/server.py: MCP server implementation with tools, prompts, and resources
• src/model_interface.py: Abstract model interface with concrete implementations for different hosting methods
• src/config.py: Configuration management using Pydantic with environment variable support

Model Interface Pattern

The codebase uses a factory pattern in create_model_interface() to instantiate the appropriate model interface:

• OllamaInterface: Uses HTTP client to communicate with Ollama API
• TransformersInterface: Direct model loading with PyTorch/Transformers
• HTTPInterface: Generic HTTP API integration

Each interface implements async methods: generate(), generate_stream(), health_check(), and get_model_info().

Development Commands

Setup and Installation

# Initial setup (runs all setup steps)
./setup.sh

# Manual setup
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

Running the Server

# Default (stdio transport with Ollama)
python src/main.py

# With specific configuration
python src/main.py --config config/default.json

# With different hosting method
python src/main.py --model-method transformers --model-path /path/to/model

# With debug logging
python src/main.py --log-level DEBUG

# HTTP transport (not yet implemented)
python src/main.py --transport http --host 0.0.0.0 --port 8080

Testing

# Run comprehensive test suite
python examples/test_server.py

# Test configuration loading
python -c "
import sys; sys.path.insert(0, 'src')
from config import AppConfig
config = AppConfig.load_from_env()
print(f'Config: {config.model.hosting_method}')"

# Test model interface directly
python -c "
import sys, asyncio; sys.path.insert(0, 'src')
from config import AppConfig
from model_interface import create_model_interface, GenerationRequest
async def test():
    config = AppConfig.load_from_env()
    interface = create_model_interface(config.model)
    health = await interface.health_check()
    print(f'Health: {health}')
asyncio.run(test())"