Metadata-Version: 2.4
Name: mcs-hooks
Version: 0.1.0
Summary: Tool-call lifecycle hooks decorator 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,hooks,lifecycle,decorator,observability
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: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcs-driver-core>=0.4.1
Dynamic: license-file

# mcs-hooks

Tool-call lifecycle hooks decorator for the **Model Context Standard (MCS)**.

`HooksDecorator` wraps a ToolDriver and emits **observability events** around
`execute_tool`:

- `pre` -- before execution: `handler(tool_name, arguments)`
- `post` -- after success: `handler(tool_name, arguments, result)`
- `on_failure` -- after an exception (then re-raised): `handler(tool_name, arguments, exc)`

Hooks are **observers** (return values ignored). To *gate* a call (confirm/deny)
use `mcs-permission`; for auth challenges use `mcs-auth`. All three stack freely:
`Hooks(Permission(Auth(RealToolDriver)))`.

## Installation

```bash
pip install mcs-hooks
```

## Usage

```python
from mcs.hooks.decorator import HooksDecorator

def audit(name, args):
    log.info("tool %s args=%s", name, args)

hooks = HooksDecorator(MyToolDriver(...), pre=[audit])
hooks.add_post_hook(lambda n, a, r: metrics.observe(n))   # multiple observers
orchestrator.add_driver(hooks, label="mail")
```

Multiple handlers per phase (observer pattern): pass lists at construction and/or
`add_*_hook` / `remove_*_hook` at runtime. Advertises the `"hooks"` capability;
reachable via `DriverMeta.resolve_capability(driver, SupportsHooks)`.

## License

Apache-2.0
