wuwa-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server for the game "鸣潮" (Wuthering Waves) that provides character and artifact information in Markdown format, optimized for Large Language Model consumption. The project uses uv for package management and requires Python ≥3.12.

Development Commands

Setup and Installation

# Install dependencies using uv
uv sync

# Install development dependencies (including ruff for linting)
uv sync --extra dev

# Install in development mode using uv
uv pip install -e .

# Alternative: Install directly from PyPI using uv
uv pip install wuwa-mcp-server

Running the Server

# Run the MCP server locally for testing
uv run python -m wuwa_mcp_server.server

# Or run with uvx (recommended for end users)
uvx wuwa-mcp-server

Build and Package

# Build the package using uv
uv build

# Alternative: Build using standard Python tools
python -m pip install build
python -m build

Code Quality

# Format all Python code
uv run ruff format .

# Check for code issues
uv run ruff check .

# Automatically fix fixable issues
uv run ruff check --fix .

Docker

# Build Docker image
docker build -t wuwa-mcp-server .

# Run Docker container (HTTP mode)
docker run -p 8081:8000 wuwa-mcp-server

# Run Docker container (STDIO mode)
docker run -e TRANSPORT=stdio wuwa-mcp-server

Publishing

• Releases are automatically published to PyPI via GitHub Actions when a release is created
• Package is available via Smithery registry for easy installation

Architecture Overview

The project follows a Domain-Driven Design (DDD) architecture with clear separation of concerns:

Core Components

1. Server (server.py)
   • FastMCP-based MCP server with three main tools
   • Dependency Injection container for service management
   • Handles both STDIO and HTTP transport modes
   • Main entry point: main() function