Metadata-Version: 2.5
Name: kx-mcp-core
Version: 0.5.0b1
Summary: Assembly layer for the kx-mcp composition container (FastMCP 3.x). Eventual home of the deferred auth/authz/identity control plane.
License-Expression: Apache-2.0
Requires-Python: <3.14,>=3.10
Requires-Dist: fastmcp<4,>=3
Requires-Dist: kx-auth-core
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pyyaml
Description-Content-Type: text/markdown

# kx-mcp-core

The assembly layer of the **KX MCP composition container**: a [FastMCP](https://gofastmcp.com) 3.x
parent that mounts pluggable backend bundles (KDB-X, KDB.AI, or your own)
into one served MCP surface, and the home of the container's control plane — inbound authentication,
the authorization seam, and per-dispatch audit.

Install it when you are **assembling an MCP server** from KX backend bundles:

```bash
uv add kx-mcp-core kx-mcp-kdbx        # from PyPI
```

> **On PyPI as a pre-release.** `0.5.0b1` is published as a PEP 440 pre-release, so an unpinned
> install resolves it only while no final release exists — pin `kx-mcp-core==0.5.0b1` if you need
> that exact version. Final releases (`0.4.0` and earlier) are on the internal KX Nexus; see the
> [deployment guide](../../docs/deployment.md#quickstart--three-ways-to-run-it) for either index.

## What's in the box

- **`make_parent(name, auth=None)`** — builds the parent server; inbound auth
  (`KX_MCP_AUTH`: `unset`/`static`/`jwks`/`entra`) and the audit middleware attach here.
- **`mount_bundle` / `try_mount_bundle`** — mount a bundle's `build_server()` under a namespace;
  the `try_` variant disables an unreachable backend instead of crashing the container.
- **The `kx-mcp` launcher** — the zero-code path: `kx-mcp --bundles kdbx,kdbai` (a bundle named
  `<name>` is the importable package `kx_mcp_<name>`).
- **`kx_mcp_core.auth`** — `current_principal()` (the validated inbound principal, visible to
  mounted tools), the `@authorize` PEP-1 capability decorator, `AuditMiddleware`, and re-exports of
  the shared `kx-auth-core` seams so bundle imports stay stable.

## Minimal glue

```python
from kx_mcp_core import make_parent, load_build_server, try_mount_bundle

app = make_parent("kx-mcp")
try_mount_bundle(app, load_build_server("kx_mcp_kdbx"), namespace="kdbx")
app.run(transport="streamable-http", host="127.0.0.1", port=8000)
```

Or no glue at all:

```bash
uvx --from kx-mcp-core --with kx-mcp-kdbx kx-mcp --bundles kdbx
```

## Documentation

The full docs live in the `kx-mcp-server-container` repository, under `docs/`: the deployment guide,
the auth reference (inbound modes, outbound strategies, authorization), and the extender guide for
writing your own bundle — plus a reference downstream build (`demos/extending/`) showing a standalone
project that assembles a server from these wheels.

All workspace packages version in lockstep from release tags — pin `kx-mcp-core` and your bundles
to the same version.
