Metadata-Version: 2.4
Name: mcs-driver-core
Version: 0.3.1
Summary: Core driver contract for the Model Context Standard.
Author-email: Danny Gerst <danny@dannygerst.de>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.modelcontextstandard.io
Project-URL: Source, https://github.com/modelcontextstandard/python-sdk
Keywords: mcs,modelcontextstandard,mcs-driver,mcs-tools,mcs-orchestrator,python-sdk,function-calling,llm,driver
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pre-commit>=3.8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: basedpyright>=1.18; extra == "dev"
Dynamic: license-file

# mcs-driver-core

Core driver contract for the **Model Context Standard (MCS)**.

This package defines the language-agnostic `MCSDriver` and `MCSToolDriver`
interfaces, metadata classes (`DriverMeta`, `DriverBinding`, `DriverResponse`),
extraction strategies, prompt strategies, and optional mixins
(`ToolCallSignaling`, `SupportsNativeTools`).

It has **zero runtime dependencies** and weighs only a few kilobytes.

## Installation

```bash
pip install mcs-driver-core
```

## Quick start

```python
from mcs.driver.core import MCSDriver, DriverMeta, DriverResponse

class MyDriver(MCSDriver):
    ...
```

## Capability detection

Optional features (health checks, native tool-calling via
`get_native_tool_context`, streaming tool-call signaling, …) are advertised as
flags in `DriverMeta.capabilities`. Each optional contract carries its flag
as a `CAPABILITY` constant. There are two operations — **detection** ("is the
feature there?") and **invocation** ("give me the object that provides it") —
and both avoid `isinstance`:

```python
from mcs.driver.core import DriverMeta, SupportsNativeTools

# detection: a pure read over the (aggregated) capability flags
if driver.meta.has_capability(SupportsNativeTools):
    ...

# invocation: get the layer that satisfies the contract -- typed, no cast,
# works whether `driver` is a plain driver, an orchestrator, or a decorator
if (dc := DriverMeta.resolve_capability(driver, SupportsNativeTools)):
    ctx = dc.get_native_tool_context(model)
```

**Do not rely on `isinstance` for feature detection.** Drivers are
composable: a *decorator* (auth, permission, hooks, …) wraps another driver,
satisfies the same `MCSDriver` / `MCSToolDriver` interfaces, and is injected
via dependency injection — so from the outside it just looks like a driver,
and the client cannot know what the stack contains. `isinstance` only sees
the **outermost** layer and misses capabilities provided deeper in the
stack. Each decorator aggregates the inner driver's `capabilities` and adds
its own, so `meta.capabilities` reflects the **whole** stack; `isinstance`
does not.

## Links

- **Homepage:** <https://www.modelcontextstandard.io>
- **Source:** <https://github.com/modelcontextstandard/python-sdk>
- **Specification:** <https://modelcontextstandard.io/Specification>

## License

Apache-2.0
