# Mist MCP Server

Reliable access to Juniper Mist from your AI tools, without writing code.

This project provides a production-grade MCP server that wraps the Mist API via
`mistapi`, so Cursor and VS Code can call Mist safely through standard MCP
tools.

## Why this exists

MCP servers make API access simple and consistent for AI tools. This server
centralizes connection and auth, validates configuration at startup, and
exposes a tool registry so non-coders can use Mist through natural language.

## Prerequisites

- Python 3.10+
- A Mist API token

## Install

No manual install required for end users. The MCP runner bootstraps the local
virtual environment on first run.

## Configure

Create a `.env` file in this folder (see `mist.env.example`):

```env
MIST_API_TOKEN=your_token_here
MIST_API_HOST=https://api.mist.com
MIST_API_TIMEOUT_SECONDS=30
```

Important: `MIST_API_HOST` must be the base host (no `/api/v1`). The server
will call the Mist “self” endpoint at startup and exit immediately if the host
or token is invalid.

## Local use (Cursor)

1. Open this project in Cursor.
2. Make sure a `mcp.json` file exists at `.cursor/mcp.json`. This repo already
   provides it, so you usually do not need to change anything.
3. Use the configuration below:

```json
{
  "mcpServers": {
    "mist": {
      "command": "${workspaceFolder}/run-mcp.sh",
      "args": [],
      "envFile": "${workspaceFolder}/.env",
      "transport": "stdio"
    }
  }
}
```

4. Restart Cursor (or reload the window).
5. Ask Cursor to call Mist tools, e.g. “list my orgs”.

## Local use (VS Code)

1. Open this project in VS Code.
2. Make sure a `mcp.json` file exists at `.vscode/mcp.json`. This repo already
   provides it, so you usually do not need to change anything.
3. Reload the window and use your MCP client to call Mist tools.

## Usage

- A tool registry is generated from the Mist SDK.
- Use `mist_search_tools` to find tools by keyword.
- Use `mist_list_groups` to discover tool groups and filter search.
- Use `mist_list_methods` to list methods in a group.
- Use `mist_describe_tool` to see parameters and details.
- Use `mist_call_tool` to execute by name with args/kwargs.
- Regenerate the registry after SDK updates via `scripts/generate_tools.py`.

## Sponsored by Hamina

<a href="https://www.hamina.com/">
  <img src="assets/hamina-logo.svg" alt="Hamina logo" width="240" height="50"/>
</a>

Built while working at Hamina.

## Development

```bash
pip install -e ".[dev]"
./.venv/bin/python scripts/generate_tools.py
pytest
ruff check .
ruff format .
mypy src
```

## Contributing

We welcome good PRs. See `CONTRIBUTING.md` for guidelines.

## License

Apache-2.0. See `LICENSE`.