鸣潮 Data Retrieval Protocol Server (WFMT-MCP)

这是一个专为《鸣潮》游戏内容设计的模型上下文协议（MCP）后端，其核心功能是检索角色数据与声骸配置信息，并将其封装为Markdown文档，以确保下游大型语言模型能够高效解析。

📄 English Documentation | 🇨🇳 中文文档

🌟 Recent Enhancements (Version 2.0.1)

• 🏗️ Architectural Overhaul: Implementation of Domain-Driven Design (DDD) principles resulting in cleaner structural partitioning.
• 🔧 Code Hygiene: Adoption of ruff for standardized formatting and static code auditing.
• 📝 Modern Typing: Transitioned to Python 3.12+ style annotations (e.g., using dict/list over legacy Dict/List).
• 🧹 Deprecation Removal: Scrubbing obsolete code segments to enforce unified stylistic standards.
• ✅ Protocol Readiness: Native integration with Smithery's emerging Streamable HTTP communication mechanism.
• 🔄 Versatile I/O: Full backward compatibility maintained for both traditional STDIO streams and the novel HTTP transport layer.
• 🌐 Cloud Agnostic: Fully prepared for deployment across cloud infrastructures like VPS, Google Cloud Run, and AWS Lambda environments.
• 📦 Dependency Management: Utilization of a dedicated Dependency Injection container for service lifecycle management.
• 🐳 Container Optimization: Leveraging uv multi-stage builds to achieve faster image creation and significantly reduced final image footprint.

Core Capabilities

• Character Attribute Retrieval: Access detailed data sets for all in-game characters.
• Echo Set Configuration Lookup: Obtain granular specifications for all available Echo Set bonuses.
• Character Dossier Access: Retrieve supplementary biographical and profile information for characters.
• LLM Optimized Output: Data structuring specifically tuned for superior large language model consumption.
• Dual Communication Pathways: Seamless switching between local STDIO and remote Streamable HTTP connection methods.

Deployment Instructions

Via Smithery Installation Manager

To automate the deployment of the WuWa MCP Server using Smithery:

bash npx -y @smithery/cli@latest install @jacksmith3888/wuwa-mcp-server --client claude --key YOUR_SMITHERY_KEYs

Direct Installation using uv

Install directly from the PyPI repository:

bash uv pip install wuwa-mcp-server

Operational Guidance

Integration with Cherry Studio

1. Acquire the Cherry Studio application.
2. Navigate to the configuration panel and select MCP Server settings.

Introduce the following configuration block:

{ "mcpServers": { "wuwa-mcp": { "command": "uvx", "args": ["wuwa-mcp-server"] } } }

Running alongside Claude Desktop

1. Download the Claude Desktop client.
2. Locate or generate your Claude Desktop configuration file:
3. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
4. Windows: %APPDATA%\Claude\claude_desktop_config.json

Append the subsequent configuration snippet:

{ "mcpServers": { "wuwa-mcp": { "command": "uvx", "args": ["wuwa-mcp-server"] } } }

1. Relaunch the Claude Desktop application for changes to take effect.

Available Tool Interfaces

1. Character Data Fetcher

python async def get_character_info(character_name: str) -> str

Queries the central repository for comprehensive character specifications, returning results formatted in Markdown.

Parameters:

• character_name: The specified character's name, provided in Chinese.

Return Value:

A Markdown string containing the character's data, or an error notification if the entity is missing or data retrieval fails.

2. Echo Set Data Provider

python async def get_artifact_info(artifact_name: str) -> str

Queries the central repository for detailed Echo Set specifications, returning results formatted in Markdown.

Parameters:

• artifact_name: The Chinese identifier for the desired Echo Set.

Return Value:

A Markdown string containing the Echo Set information, or an error message if the set is unlocatable or data acquisition encounters errors.

3. Character Biography Retriever

python async def get_character_profile(character_name: str) -> str

Retrieves the narrative profile data for a specified character, delivered in Markdown format.

Parameters:

• character_name: The character's full name in Chinese.

Return Value:

A Markdown string containing the character's biographical details, or an error indication upon lookup failure or data unavailability.

Development & Quality Assurance

Local Execution Commands

bash

Standard I/O Mode (Default)

uv run python -m wuwa_mcp_server.server

HTTP Transport Mode

TRANSPORT=http uv run python -m wuwa_mcp_server.server

Code Quality Enforcement

The project mandates the use of ruff for maintaining consistent code styling and performing static analysis checks.

Installing Development Dependencies

bash uv sync --extra dev

Formatting and Linting Operations

bash

Apply formatting across all Python source files

uv run ruff format .

Execute static analysis checks

uv run ruff check .

Attempt automatic remediation of fixable issues

uv run ruff check --fix .

Ruff Configuration Summary

The project adheres to the following quality parameters:

• Line Length Limit: 120 characters.
• Target Interpreter Version: 3.12.
• Active Rule Sets: Includes pycodestyle, pyflakes, isort standards, naming conventions, pyupgrade checks, bugbear analysis, code simplification rules, etc.
• Import Ordering: Enforces single-line imports with project-specific modules prioritized.

Containerized Deployment

bash

Build the Docker image

docker build -t wuwa-mcp-server .

Run container using HTTP listener on port 8081 (mapping to container's 8000)

docker run -p 8081:8000 wuwa-mcp-server

Run container explicitly forcing STDIO transport via environment variable

docker run -e TRANSPORT=stdio wuwa-mcp-server

Detailed Functionality Breakdown

Data Formatting Layer

• Processes and cleans data retrieved from the primary repository.
• Structures output specifically for optimized consumption by LLMs.
• Leverages asynchronous operations for parallel processing efficiency.
• Non-blocking I/O design to prevent service stalls.

Communication Modalities

• STDIO Communication: Primary mode for local interfaces, such as Claude Desktop.
• Streamable HTTP Communication: Preferred method for remote access and cloud deployments.
• Transport mode is dynamically selected based on the TRANSPORT environment variable setting.

Contribution Guidelines

We welcome feature suggestions and Pull Requests! Potential areas for immediate enhancement include:

• Expanding supported data domains beyond current scope.
• Introducing granular options for content parsing.
• Implementing a robust caching mechanism for frequently accessed entity data.
• Adding support for multilingual output localization.

Licensing

This software is distributed under the permissive MIT License.

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea