Metadata-Version: 2.4
Name: taranis-mcp-server
Version: 0.1.1
Summary: MCP server for Taranis AI
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<3,>=2
Requires-Dist: pydantic-settings<3,>=2.10
Description-Content-Type: text/markdown

# Taranis MCP Server

<!-- mcp-name: io.github.taranis-ai/taranis-mcp-server -->

A read-oriented Model Context Protocol server for Taranis AI. The current version exposes the `list_stories` and `list_sources` tools over stdio or authenticated Streamable HTTP.

## Configuration

You need a reachable Taranis instance and a user with `ASSESS_ACCESS`. Set `TARANIS_API_URL` to the complete API root, including `/api`, then choose exactly one authentication mode:

- `TARANIS_USERNAME` and `TARANIS_PASSWORD`: the server logs in lazily and can log in again after an expired JWT.
- `TARANIS_ACCESS_TOKEN`: use an existing JWT returned by Taranis `/api/auth/login`; it cannot be renewed without credentials.

Do not reuse a Taranis JWT as `MCP_ACCESS_TOKEN`. The latter protects the MCP HTTP endpoint and is not needed for stdio.

## Installation and MCP Client Configuration

This server is intended for desktop AI assistants as well as developer tools. Desktop applications with MCP support include Claude Desktop and OpenAI's ChatGPT desktop app. IDE and terminal clients include Cursor, Zed, Codex CLI, and the Codex IDE extension. If another assistant, such as Mistral Le Chat, offers MCP integration in your installed version or workspace, use its local stdio or remote Streamable HTTP configuration as appropriate.

Clients that support local stdio can launch the server as a child process. The configuration file location and surrounding schema depend on the client, but the server command, arguments, and environment are the same. Desktop applications that support only remote MCP connectors should use the Streamable HTTP setup below instead.

### PyPI with uvx

This option installs and runs the package without cloning the repository. Install [uv](https://docs.astral.sh/uv/), then add the following definition to a client that uses the `mcpServers` format, such as Claude Desktop or Cursor:

```json
{
  "mcpServers": {
    "taranis": {
      "command": "/absolute/path/to/uvx",
      "args": ["taranis-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "TARANIS_API_URL": "https://taranis.example/api",
        "TARANIS_USERNAME": "analyst",
        "TARANIS_PASSWORD": "change-me"
      }
    }
  }
}
```

Use `which uvx` on Linux/macOS or `where uvx` on Windows to find the executable. On Windows the path may end in `uvx.exe`. An absolute path is recommended because desktop applications may have a smaller `PATH` than an interactive shell.

### Container with Docker

This option requires only Docker. On Windows, install and start Docker Desktop before launching the MCP client. The client passes its configured environment variables to `docker`, and the `-e` arguments forward them into the container:

```json
{
  "mcpServers": {
    "taranis": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "TARANIS_API_URL",
        "-e",
        "TARANIS_USERNAME",
        "-e",
        "TARANIS_PASSWORD",
        "ghcr.io/taranis-ai/taranis-mcp-server:stable"
      ],
      "env": {
        "TARANIS_API_URL": "https://taranis.example/api",
        "TARANIS_USERNAME": "analyst",
        "TARANIS_PASSWORD": "change-me"
      }
    }
  }
}
```

The `stable` tag follows the newest stable container release. Replace it with an exact tag such as `0.1.1` for a reproducible installation. Likewise, append a version to the PyPI argument, such as `taranis-mcp-server==0.1.1`, to pin that installation.

For either installation method, use a JWT by replacing the username and password with `TARANIS_ACCESS_TOKEN`. In the Docker arguments, also replace the two credential `-e` entries with `"-e", "TARANIS_ACCESS_TOKEN"`.

### MCP Registry

Starting with version `0.1.1`, releases are published as `io.github.taranis-ai/taranis-mcp-server` in the official MCP Registry. Registry-aware applications can use that identity to discover the server and choose either its PyPI or OCI package. The registry does not define one universal install command, so the final confirmation and configuration flow depends on the application.

Do not commit a project-level MCP configuration containing credentials. Restart or reload the client after saving its configuration. Its MCP settings should show a `taranis` server with the `list_stories` and `list_sources` tools. For clients such as Zed that use a different configuration schema, carry over the same command, argument list, and environment values into that client's stdio MCP definition.

### Codex

Codex CLI and the Codex IDE extension share MCP configuration from `~/.codex/config.toml`. Add this server definition, replacing the absolute path:

```toml
[mcp_servers.taranis]
command = "/absolute/path/to/uvx"
args = ["taranis-mcp-server"]
env_vars = ["TARANIS_USERNAME", "TARANIS_PASSWORD"]

[mcp_servers.taranis.env]
MCP_TRANSPORT = "stdio"
TARANIS_API_URL = "https://taranis.example/api"
```

Export the forwarded credentials before starting Codex:

```bash
export TARANIS_USERNAME=analyst
export TARANIS_PASSWORD=change-me
codex mcp list
codex
```

Use `/mcp` inside the Codex TUI to confirm that `taranis` is active and exposes `list_stories` and `list_sources`. To use a JWT instead, replace the two names in `env_vars` with `TARANIS_ACCESS_TOKEN` and export that variable.

## Streamable HTTP

For a separately running server, configure `MCP_TRANSPORT=streamable-http`, set a strong `MCP_ACCESS_TOKEN`, and start:

```bash
uv run --frozen taranis-mcp-server
```

The default endpoint is `http://127.0.0.1:8000/mcp`. Clients must send `Authorization: Bearer <MCP_ACCESS_TOKEN>`. For a non-local deployment, configure `MCP_PUBLIC_URL`, `MCP_ISSUER_URL`, `MCP_ALLOWED_HOSTS`, and `MCP_ALLOWED_ORIGINS` for the externally visible address, and terminate TLS at a trusted reverse proxy.

## Development from Source

Development requires Python 3.12 or newer and [uv](https://docs.astral.sh/uv/). Clone the repository, copy `.env.example` to `.env`, and install the locked dependencies:

```bash
uv sync --frozen
```

Run the server using the configuration from `.env`:

```bash
uv run --frozen taranis-mcp-server
```

Run the development checks:

```bash
uv run --frozen pytest
uv run --frozen ruff check .
```
