# ZpDIC MCP Server

[繁體中文](README.zh.md) | [日本語](README.ja.md)

An MCP server that allows ChatGPT to use the ZpDIC API.

## Prerequisites

- Node.js and npm
- A ZpDIC API key
- An ngrok account and authtoken

## Installation

Clone this repository and install the dependencies:

```sh
git clone https://github.com/Eskartur/ZpDIC-MCP.git
cd zpdic-mcp
npm install
```

## Environment Variables

Create a `.env` file in the project root:

```sh
ZPDIC_API_KEY=your_zpdic_api_key_here
NGROK_AUTHTOKEN=your_ngrok_authtoken_here
```

### Getting `ZPDIC_API_KEY`

Log in to your ZpDIC account, open your user page, and go to the Developer tab to create or copy your API key.

Keep this key private because it allows the server to read and modify dictionary data through your ZpDIC account.

### Getting `NGROK_AUTHTOKEN`

Create or log in to an ngrok account, then open [Your Authtoken](https://dashboard.ngrok.com/get-started/your-authtoken) in the ngrok dashboard and copy it into `NGROK_AUTHTOKEN`.

The server uses this token to create a public HTTPS tunnel for your local MCP server.

## Run the Server

Start the server with npm:

```sh
npm start
```

The server listens locally on port `6767` and prints output similar to:

```txt
Server running on http://localhost:6767
MCP available at: https://example.ngrok-free.app/mcp
```

Copy the full `MCP available at` URL, including the `/mcp` path.

## Add to ChatGPT

In ChatGPT settings, open Apps -> Create app. Use the public ngrok URL printed by the server as the server URL:

```txt
https://example.ngrok-free.app/mcp
```

After saving it, ChatGPT can use the ZpDIC tools exposed by this server.

## Tools

This MCP server provides the following tools:

- `get_word_by_number`: Retrieves a single word entry by its word number.
- `search_words`: Searches word entries in a dictionary.
- `create_word`: Creates a new word entry in a dictionary.
- `delete_word`: Deletes a word entry by its word number.
- `overwrite_word`: Overwrites a word entry by its word number. Fields omitted from the new data are cleared.
- `get_example_sentences`: Retrieves example sentences for a word by its word number.

All tools share the same ZpDIC API rate limit (10 requests per minute). The MCP server automatically waits when needed and retries requests after rate limit responses.

## Notes

- Keep the terminal running while using the ChatGPT app.
- The ngrok URL stays the same when you use the same ngrok account.
- Do not commit your `.env` file or share your API keys.