Metadata-Version: 2.4
Name: kleia
Version: 0.1.0
Summary: HTTP client adapters (CLI + stdio MCP) for a running Kleia.
License-Expression: MIT
License-File: LICENSE
Requires-Dist: httpx>=0.23.0,<1
Requires-Dist: keyring>=25
Requires-Dist: mcp>=2.2.0,<2.3
Requires-Dist: platformdirs>=4.10.0
Requires-Dist: toon-format>=1.1.0,<2
Requires-Dist: typer>=0.26.7
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# Kleia client

Command-line client and stdio MCP server for a running **Kleia** instance. Kleia is a read-only reader for an
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/open-knowledge-format) (OKF) Knowledge Bundle; this
package lets coding agents and scripts read, search and list the Concepts in a bundle through it.

You need a running Kleia to point it at. This package does not include the server.

Requires Python 3.14 or newer.

## Install

```bash
uvx kleia --help          # run without installing
pip install kleia         # or install
```

This provides two commands:

- `kleia`: the Agent CLI. Output is compact [TOON](https://github.com/toon-format) by default; commands such as
  `read` take `--json` for the complete envelope.
- `kleia-mcp`: a stdio MCP server exposing the same operations as tools.

## Connect

Save your Kleia URL once as a profile, then use any command:

```bash
kleia configure https://kleia.example.com
kleia status
```

If the instance requires sign-in, run `kleia login`. It opens your browser, and the sign-in is stored for the profile
(`kleia logout` removes it). A Kleia running in public mode needs no sign-in.

## Commands

| Command | What it does |
|---|---|
| `kleia status` | Compact Source Status of the connected instance |
| `kleia list-concepts` | List the Concepts in the active bundle |
| `kleia list-readable` | List every readable file in the bundle |
| `kleia read` | Read a Concept or document by Concept ID or path |
| `kleia search "<query>"` | Search the bundle |
| `kleia relationships` | Incoming and outgoing links for one document |
| `kleia wait-until-fresh` | Block until the index is fresh |
| `kleia profiles` | Manage saved connection profiles |
| `kleia setup` | Install session integrations for Claude Code, Codex and OpenCode in the current directory |

Run `kleia <command> --help` for options.

## MCP

Add the stdio server to an MCP client, for example:

```json
{
  "mcpServers": {
    "kleia": {
      "command": "uvx",
      "args": ["--from", "kleia", "kleia-mcp", "--base-url", "http://127.0.0.1:8000"]
    }
  }
}
```

A Kleia instance also serves MCP over HTTP at `/mcp`; use that when you would rather connect to the server directly.

## License

MIT.
