MushcodeMCP Server

A specialized Model Context Protocol server for MUSHCODE development assistance

🚀 Quick Start

Installation

# Global installation (recommended)
npm install -g mushcode-mcp-server

# Or local installation
npm install mushcode-mcp-server

Usage

# Start MCP server (stdio mode for Claude Desktop)
mushcode-mcp-server start

# Start network server (HTTP/REST API)
mushcode-mcp-server network --port 3001

# List available tools
mushcode-mcp-server tools

# Create default configuration
mushcode-mcp-server init

🛠️ Available Tools

The server provides 7 specialized MUSHCODE tools:

• generate_mushcode - Generate MUSHCODE from natural language descriptions
• validate_mushcode - Validate syntax, security, and best practices
• optimize_mushcode - Optimize code for performance and readability
• explain_mushcode - Explain how MUSHCODE works with detailed breakdowns
• get_examples - Get relevant examples with learning paths
• format_mushcode - Format code for improved readability
• compress_mushcode - Minify code while preserving functionality

📋 MUD Server Support

• PennMUSH - Full support
• TinyMUSH - Full support
• RhostMUSH - Full support
• TinyMUX - Full support

🔌 Integration Options

Option 1: Claude Desktop (MCP Protocol)

Add to your ~/.config/claude-desktop/config.json:

{
  "mcpServers": {
    "mushcode-mcp-server": {
      "command": "mushcode-mcp-server",
      "args": ["start"]
    }
  }
}

Option 2: REST API

# Start network server
mushcode-mcp-server network --port 3001

# Use REST API
curl -X POST http://localhost:3001/api/tools/generate_mushcode \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "description": "Create a teleportation command",
      "server_type": "PennMUSH"
    }
  }'

Option 3: Programmatic Usage

import { MushcodeProtocolHandler } from 'mushcode-mcp-server';
import { getConfig } from 'mushcode-mcp-server/config';

const configManager = getConfig();
const handler = new MushcodeProtocolHandler(configManager);
await handler.registerDefaultTools();

const registry = handler.getRegistry();
const result = await registry.callTool('generate_mushcode', {
  description: 'Create a room object',
  server_type: 'PennMUSH'
});

⚙️ Configuration

Create Configuration File

# Create default config
mushcode-mcp-server init

# Validate configuration
mushcode-mcp-server config

Example Configuration

{
  "server": {
    "name": "mushcode-mcp-server",
    "version": "1.0.0"
  },
  "tools": {
    "enabled": [
      "generate_mushcode",
      "validate_mushcode", 
      "optimize_mushcode",
      "explain_mushcode",
      "get_examples",
      "format_mushcode",
      "compress_mushcode"
    ],
    "defaultServerType": "PennMUSH"
  },
  "knowledge": {
    "cacheEnabled": true,
    "cacheSize": 1000
  }
}

🌐 Network Mode Features

When running in network mode, you get:

• REST API endpoints for all tools
• Server-Sent Events for MCP over HTTP
• CORS support for web applications
• Rate limiting and security features
• Health checks for monitoring

API Endpoints

• GET /health - Health check
• GET /api/tools - List available tools
• POST /api/tools/{toolName} - Execute a tool
• GET /sse - MCP over Server-Sent Events

🔒 Security Features

• Input validation and sanitization
• Rate limiting (configurable)
• API key authentication (optional)
• CORS protection
• Security vulnerability detection

📊 Performance

• Knowledge base caching for fast responses
• Lazy loading of resources
• Response time optimization
• Memory-efficient processing

🐳 Docker Support

# Using the published Docker image
docker run -p 3001:3001 mushcode-mcp-server:latest

# Or build locally
docker build -t mushcode-mcp-server .
docker run -p 3001:3001 mushcode-mcp-server

📚 Examples

Generate a Command

mushcode-mcp-server network --port 3001 &

curl -X POST http://localhost:3001/api/tools/generate_mushcode \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "description": "Create a command that teleports players to a random room",
      "server_type": "PennMUSH",
      "function_type": "command",
      "security_level": "builder"
    }
  }'

Validate Code

curl -X POST http://localhost:3001/api/tools/validate_mushcode \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "code": "&CMD.TELEPORT me=$+teleport *:@tel %#=[random(rooms())]",
      "server_type": "PennMUSH",
      "check_security": true
    }
  }'

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📄 License

MIT © lcanady

🔗 Links

• GitHub Repository
• Documentation
• Issues
• Changelog

⭐ Support

If you find this package helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting features
• 🤝 Contributing code

Made with ❤️ for the MUD development community