# ngmcp

`ngmcp` is an [MCP](https://modelcontextprotocol.io/) server that exposes
[Norton Guide](https://en.wikipedia.org/wiki/Norton_Guides) database files
to AI agents. It is built on top of the
[`ngdb`](https://github.com/davep/ngdb.py) library and uses
[`fastmcp`](https://github.com/jlowin/fastmcp) as its MCP framework.

Norton Guides are a classic hypertext help-file format from the DOS era,
used widely for
[Clipper](https://en.wikipedia.org/wiki/Clipper_(programming_language)) and
similar tool documentation.

## Installation

NGMCP requires Python 3.12 or later.

### Using uv (recommended)

The fastest and most modern way to install NGMCP is with
[uv](https://github.com/astral-sh/uv):

```bash
uv tool install ngmcp
```

If you don't have `uv` installed you can use [uvx.sh](https://uvx.sh) to
perform the installation. For GNU/Linux or macOS or similar:

```sh
curl -LsSf uvx.sh/ngmcp/install.sh | sh
```

or on Windows:

```sh
powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/ngmcp/install.ps1 | iex"
```

### Using pipx

```bash
pipx install ngmcp
```

## Configuration

How you configure your agent to use the server will depend on the agent
you're using. Generally the configuration to use will be:

```json
{
  "mcpServers": {
    "ngmcp": {
      "command": "ngmcp",
      "args": [],
      "env": {
        "NGMCP_GUIDE_DIRS": "/path/to/your/ng/files"
      }
    }
  }
}
```

> [!note]
> Adjust the `command` and `args` depending on your installation method.

## Configuration

| Environment variable        | Default | Description                                                    |
|-----------------------------|---------|----------------------------------------------------------------|
| `NGMCP_GUIDE_DIRS`          | *(none)*| Colon-separated list of directories to search for `.ng` files  |
| `NGMCP_ALLOW_ABSOLUTE_PATHS`| `false` | Allow tools to open `.ng` files by absolute path               |

## Available Tools

| Tool                | Description                                                                |
|---------------------|----------------------------------------------------------------------------|
| `get_guide_info`    | Title, credits, magic, `made_with`, menu count, and file size              |
| `list_menus`        | Menu structure: title and prompt list for each menu                        |
| `list_entries`      | All entries with type, offset, line count, and first line of text          |
| `read_entry`        | Full plain-text content of the entry at a given offset                     |
| `read_entry_source` | Full plain-text Norton Guide source content of the entry at a given offset |
| `follow_link`       | Follow a short-entry link to the target long entry                         |
| `line_search_guide` | Line-oriented full-text search through all entries                         |
| `body_search_guide` | Full-body-oriented full-text search through all entries                    |
| `list_guide_files`  | `.ng` files in the configured guide directories                            |

## Hacking

See [Contributing.md](Contributing.md).

```bash
git clone https://github.com/davep/ngmcp
cd ngmcp
make setup
make checkall
```

[//]: # (README.md ends here)