Face Generator MCP Server: Generate Human Faces with Ease

Features

This project provides a Model Context Protocol (MCP) server for generating human face images using https://thispersondoesnotexist.com. Think of it as a tool that lets other applications, like Cline, generate realistic-looking faces on demand.

This guide is designed for beginners, so we'll walk through everything step-by-step. We'll cover:

1. Prerequisites: What you need before you start.

2. Installation and Setup: Getting everything up and running.

3. Running the Server: Starting the server.

4. Integrating with Cline: Connecting this server to the Cline VS Code extension.

5. Troubleshooting: Common problems and solutions.

6. Tool Parameters: A list of the parameters you can use with the `generate_face` tool.

1. Prerequisites

Before you begin, you'll need a few things:

• Node.js and npm: Node.js is a JavaScript runtime that lets you run JavaScript code outside of a web browser. npm (Node Package Manager) is included with Node.js and is used to install packages (libraries of code).

node -v
        npm -v

You should see version numbers for both Node.js and npm. If you see an error, Node.js might not be installed correctly, or it might not be in your system's PATH. (See Troubleshooting below).

2. Installation and Setup

Let's get the project code and set it up:

1. Clone the Repository:

1. Open a terminal (command prompt or Terminal).

2. Navigate to the directory where you want to store the project. For example, to put it on your Desktop:

cd Desktop

3. Clone the repository:

git clone https://github.com/Moe/mcp-face-generator

4. Change into the project directory:

cd mcp-face-generator

1. Open GitHub Desktop.

2. Click "File" -> "Clone Repository...".

3. In the "URL" tab, paste the repository URL.

4. Choose a local path (where you want to save the project on your computer).

5. Click "Clone".

2. Install Dependencies: This downloads all the necessary libraries the project needs. In the terminal, inside the project directory, run:

npm install

This might take a few minutes.

3. Build the Project: This compiles the code into an executable format.

npm run build

3. Running the Server

You can run the server in two main ways:

• Standalone Mode: This runs the server directly, and it will output messages to the terminal.
• Development/Debug Mode: This runs the server with the MCP Inspector. You can open the URL that it outputs in your browser and start playing around.

3.1 Standalone Mode

To run the server in standalone mode, use the following command in the terminal (from the project directory):

npm run start

You should see messages in the terminal indicating that the server is running. It will listen for connections from MCP clients. The server will keep running until you stop it (usually with Ctrl+C).

3.2 Development/Debug Mode (with Inspector)

This mode is useful for debugging.

1. Start the server in debug mode:

npm run dev

This will start the server and output a message like: `🔍 MCP Inspector is up and running at http://localhost:5173 🚀`. This is the URL you'll use to open the MCP inspector in your Browser.

4. Integrating with Cline

Cline is a VS Code extension that uses MCP servers to provide language support. Here's how to connect this face generator server to Cline:

1. Install Cline: If you haven't already, install the "Cline" extension in VS Code.

2. Open Cline Settings:

3. Add the Server Configuration: You'll need to add an entry to the `servers` array in the `cline_mcp_settings.json` file. Here's an example:

{
      "mcpServers": {
        "face-generator": {
          "command": "node",
          "args": [
            "C:/PATH_TO/mcp-face-generator/build/index.js"
          ],
          "disabled": false,
          "autoApprove": []
        }
      }
    }

4. Test the Connection:

5. Troubleshooting

• `node -v` or `npm -v` gives an error:
• `npm install` fails:
• Cline doesn't connect to the server:

6. Tool Parameters

The `generate_face` tool accepts the following parameters:

• `outputDir`: (required) Directory to save the images
• `fileName`: Optional file name (defaults to timestamp)
• `count`: Number of images to generate (default: 1)
• `width`: Image width in pixels (default: 256)
• `height`: Image height in pixels (default: 256)
• `shape`: Image shape (square|circle|rounded, default: square)
• `borderRadius`: Border radius for rounded shape (default: 32)
• `returnImageContent`: Return image as base64 encoded content instead of file path (default: false)

Example

{
  "outputDir": "./output",
  "count": 3,
  "width": 512,
  "height": 512,
  "shape": "circle",
  "returnImageContent": true
}

License

MIT