# namegen-mcp

An MCP server that mirrors the behaviour of [https://names.ironarachne.com](https://names.ironarachne.com), backed by the `@ironarachne/made-up-names` dataset. It exposes a single tool, `generate-names`, which accepts `race`, `type`, and `number` arguments to return randomly generated names. The defaults match the hosted API (`race` defaults to `human`, `number` defaults to `1`).

## Prerequisites

- Node.js 18 or newer
- npm 9 or newer (ships with recent Node.js distributions)

## Installation

```bash
npm install
```

This downloads the MCP SDK and the name generation dataset locally so the server operates without any external network calls.

## Running the server

### Development (hot reload)

```bash
npm run dev
```

`tsx` compiles the TypeScript entry point in-memory and wires the server to stdio, which is the transport expected by most MCP-compatible clients.

### Production build

```bash
npm run build
npm start
```

This emits the compiled files into `dist/` and runs the stdio server from the generated JavaScript.

## Using with Claude Desktop (and other MCP frontends)

1. Open Claude Desktop and navigate to **Settings → Developer → Model Context Protocol**.
2. Add a new MCP server entry with one of the following command setups (update `cwd` to wherever you cloned the repo). Claude’s configuration expects servers inside a `mcpServers` object, so the full JSON looks like this:
   ```json
   {
     "mcpServers": {
       "namegen": {
         "command": "npm",
         "args": ["start"],
         "cwd": "/absolute/path/to/namegen-mcp"
       }
     }
   }
   ```
   To run the TypeScript entry without a prior build, swap the command block for the following:
   ```json
   {
     "mcpServers": {
       "namegen": {
         "command": "npx",
         "args": ["tsx", "src/server.ts"],
         "cwd": "/absolute/path/to/namegen-mcp"
       }
     }
   }
   ```
   **Important:** Set `cwd` to the project root (the folder containing `package.json`). Pointing it at `dist/` or another subdirectory will make `npm` fail to locate the scripts file and the server exits with code 1.
   If you use the Settings UI, Claude writes this JSON for you; if you edit `claude-desktop-config.json` manually, be sure to keep the `mcpServers` wrapper or the app will report “Invalid config: missing mcpServers object.”

3. For the `npm start` variant, run `npm run build` once so `dist/server.js` is available. The `npx tsx` command path does not require a pre-build.
3. Save the configuration and restart Claude Desktop if it does not immediately recognise the new server.

Any other MCP-compatible frontend that supports stdio transports can use the same command/args/cwd configuration to launch this project.

## Tool reference

- **Tool ID:** `generate-names`
- **Parameters:**
  - `race` (string, optional, default `"human"`)
  - `type` (string, required, one of `male`, `female`, `family`, `given`, `region`, `town`, `culture`)
  - `number` (integer, optional, default `1`, maximum `50`)
- **Response:** The tool returns a JSON payload with the canonical `race`, requested `type`, requested `count`, and an array of generated `names`. The same payload is returned as structured content and rendered text for convenience.

Two static resources are also registered:

- `namegen://races` – JSON list of valid race identifiers
- `namegen://name-types` – JSON list of valid name types

## Example

Requesting three female elf names via an MCP client might return a payload like the following:

```json
{
  "race": "elf",
  "type": "female",
  "count": 3,
  "names": [
    "Aerithain",
    "Nylenna",
    "Valesri"
  ]
}
```

Because all content is generated locally, the server can run offline after the initial dependency installation.

## Troubleshooting

- **Server exits immediately with code 1 in Claude:** make sure the `cwd` in your MCP configuration points to the repository root (where `package.json` lives) and that you ran `npm install`. If you use the `npm start` command, run `npm run build` once so `dist/server.js` exists.