werewolfMCP

# Werewolf MCP Server and Client This project is a multi-client protocol (MCP) server and example client for the Werewolf game implemented in TypeScript. ## Tech Stack * **Server:** * Runtime: Node.js (recommended v18 or higher) * Framework: Fastify * Language: TypeScript * Database: MySQL (using `mysql2/promise`) * Network Communication: WebSocket (`@fastify/websocket`) * Testing: Jest (`ts-jest`) * Authentication: JWT (`jsonwebtoken`), Password Hashing (`bcrypt`) * Configuration: `dotenv`, `js-yaml` * Others: `uuid` * **Client:** * Runtime: Node.js * Language: TypeScript * Network Communication: WebSocket (`ws`) * Others: `uuid` ## Project Structure ``` . ├── client/ # Example client code │ ├── src/ │ │ ├── main.ts # Client entry point and example usage │ │ ├── mcp-client.ts # Basic MCP client (connection, request/response, events) │ │ └── werewolf-client.ts # Werewolf MCP tool implementation │ ├── package.json │ └── tsconfig.json ├── md/ # Project design documents and specifications │ ├── create_mcp_server_instructions.md │ ├── werewolf_mcp_client_tools.md │ └── werewolf_mcp_server_architect.md ├── server/ # Server code │ ├── config/ # Example configuration files │ │ ├── game_templates.example.yaml │ │ └── server.example.json │ ├── migrations/ # Database migration scripts │ │ └── 001_initial_schema.sql │ ├── src/ # Server source code │ │ ├── config/ # Configuration service │ │ ├── core/ # Core types, constants, roles, ability definitions │ │ ├── network/ # WebSocket handling, MCP parsing, connection management │ │ ├── services/ # Business logic services (authentication, lobby, game, persistence) │ │ ├── types/ # TypeScript type definitions │ │ ├── utils/ # Utility functions (logging, random numbers) │ │ └── server.ts # Fastify server entry point │ ├── tests/ # Unit tests and integration tests │ ├── .env.example # Environment variable example │ ├── jest.config.js │ ├── package.json │ └── tsconfig.json ├── .gitignore ├── communication_log.md # Development communication log (detailed record of the development process) └── README.md # This file ``` ## Server Setup and Running 1. **Database Setup:** * Ensure you have a running MySQL server. * Create a new database (e.g., `werewolf_mcp`). * Connect to your MySQL server and execute the SQL statements in the `server/migrations/001_initial_schema.sql` file to create the required tables. ```bash mysql -u <your_username> -p <your_database_name> < server/migrations/001_initial_schema.sql ``` 2. **Environment Variable Configuration:** * Navigate to the `server/` directory: `cd server` * Copy the environment variable example file: `cp .env.example .env` * Edit the `.env` file to fill in your database connection information and JWT configuration: * `DB_HOST`: Database hostname (e.g., `localhost`) * `DB_PORT`: Database port (e.g., `3306`) * `DB_USER`: Database username * `DB_PASSWORD`: Database password * `DB_DATABASE`: The name of the database you created (e.g., `werewolf_mcp`) * `JWT_SECRET`: The key used to issue JWTs (a secure random string) * `JWT_EXPIRES_IN`: The validity period of the JWT (e.g., `1h`, `7d`) * `BCRYPT_SALT_ROUNDS` (optional): The number of rounds for bcrypt hashing, default is 10. * `SERVER_PORT` (optional): The port the server listens on, default is 3000. * `LOG_LEVEL` (optional): Log level (e.g., `info`, `debug`), default is `info`. 3. **Install Dependencies:** * Ensure you are in the `server/` directory. * Run: `npm install` 4. **Compile TypeScript:** * Ensure you are in the `server/` directory. * Run: `npm run build` * This will compile the TypeScript code in the `src/` directory into JavaScript in the `dist/` directory. 5. **Run the Server:** * Ensure you are in the `server/` directory. * Run: `npm start` * Or directly run the compiled file: `node dist/server.js` * The server will start on the configured port (default is 3000) and listen for WebSocket connections. 6. **Run Tests:** * Ensure you are in the `server/` directory. * Run: `npm test` * All tests should pass (fixed during the development process). ## Client Setup and Running The client is a basic example demonstrating how to interact with the server via the MCP protocol. 1. **Install Dependencies:** * Navigate to the `client/` directory: `cd client` * Run: `npm install` 2. **Compile TypeScript:** * Ensure you are in the `client/` directory. * Run: `npm run build` * This will compile the TypeScript code in the `src/` directory into JavaScript in the `dist/` directory. 3. **Run the Example Client:** * Ensure you are in the `client/` directory. * Run: `npm start` * Or directly run the compiled file: `node dist/main.js` * The client will attempt to connect to `ws://localhost:3000/mcp` (or the address configured on the server), performing a series of basic operations such as registration, login, creating/joining games, and preparing, while listening for and printing the `GameStateUpdate` events pushed by the server. ## MCP Interface * The server provides the MCP interface via WebSocket. * Default address: `ws://localhost:3000/mcp` (the port can be configured in the server's `.env` or `server/config/server.example.json`). * For client tool specifications, see: `md/werewolf_mcp_client_tools.md`. ## Future Work / Known Limitations * **Client:** * Type definitions are relatively loose (using `any`), and shared type definitions with the server can enhance type safety. * The example client (`main.ts`) only demonstrates basic flows and does not include any actual game strategies or decision-making logic based on `GameStateUpdate`. * **Server:** * There are some `// TODO:` comments in the code marking areas for further improvement, such as: * More refined player visibility filtering rules (`generateFilteredGameState`). * Dedicated MCP routes or handling logic for specific role abilities. * Configurability of game phase timers. * Dependency injection is currently done manually in `server.ts`, and a dedicated DI container (like `tsyringe` or `inversifyJS`) could be introduced for improvement. * WebSocket error handling could be more granular, mapping specific MCP errors.