Metadata-Version: 2.4
Name: taranis-mcp-server
Version: 0.1.0
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

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

## Requirements

- Python 3.12 or newer
- [uv](https://docs.astral.sh/uv/)
- A reachable Taranis instance and a user with `ASSESS_ACCESS`

Install the locked dependencies:

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

## Configuration

Copy `.env.example` to `.env` for command-line use. 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.

## Desktop Apps 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.

Claude Desktop and Cursor support the following `mcpServers` definition directly. Add it to `claude_desktop_config.json`, a Cursor user-level MCP configuration, or `.cursor/mcp.json`, replacing the repository path, `uv` path, Taranis URL, and credentials:

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

Use `which uv` on Linux/macOS or `where uv` on Windows to find the executable. An absolute path is recommended because desktop applications may have a smaller `PATH` than an interactive shell. To use a JWT instead of username/password, replace both credential entries with `"TARANIS_ACCESS_TOKEN": "replace-with-a-taranis-jwt"`.

Do not commit a project-level MCP configuration containing credentials; this repository ignores `.cursor/mcp.json` for that reason. Restart or reload the client after saving its configuration. Its MCP settings should show a `taranis` server with the `list_stories` tool. 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, the Codex IDE extension, and the ChatGPT desktop app share MCP configuration from `~/.codex/config.toml`. Add this server definition, replacing both absolute paths:

```toml
[mcp_servers.taranis]
command = "/absolute/path/to/uv"
args = [
  "run",
  "--frozen",
  "--project",
  "/absolute/path/to/taranis-mcp-server",
  "taranis-mcp",
]
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`. 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
```

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 checks

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