Metadata-Version: 2.5
Name: nlalpha-capability
Version: 0.3.0
Summary: NLAlpha capability discovery MCP server.
Project-URL: Homepage, https://github.com/ruimarj/nlalpha-capability
Project-URL: Repository, https://github.com/ruimarj/nlalpha-capability
Project-URL: Issues, https://github.com/ruimarj/nlalpha-capability/issues
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Requires-Python: <3.13,>=3.12
Requires-Dist: mcp<2.0,>=1.6.0
Requires-Dist: nlalpha-core[json-log,telemetry]>=0.7.0
Requires-Dist: starlette>=0.37
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# nlalpha-capability

Capability discovery MCP server for the NLAlpha quantitative strategy workflow engine.

## Positioning

This package is independent of strategy generation (`nlalpha-strategy`) and backtest execution (`nlalpha-backtest`). It only exposes capability discovery tools for agents to query available helpers by domain and decide which capabilities to call.

## Tools

- `list_capability_domains()`: returns the exact `domain` labels that currently have available helpers.
- `list_capabilities_by_domain(domain)`: matches helper `domain` exactly; returns name, `category` (`function` or `property`), signature, description, source plugin, and read-only flag.
- `list_family_helpers(family, domain="")`: returns helpers of a discovered strategy family; an empty domain returns all helpers of that family.
- `list_capability_providers()`: returns entry point, distribution, version, manifest classification, and helper count for each available provider.
- `diagnose_providers()`: returns installed but unavailable or failed capability/family plugins with reasons. Uninstalled optional plugins are not reported as failures.

Provider manifest `domains` are provider classifications; helper `domain` is a per-helper label. They are stored and queried under different contracts. `category` indicates a function or a read-only property and is not a domain. Provider discovery caches one instance and result per entry point; only providers with `available` status and a valid manifest enter the catalog.

Stable provider identities currently include `talib`, `performance`, and `statistics_impl`. When an optional dependency is missing, an installed plugin keeps the same provider ID and appears in diagnostics as unavailable with a reason; the catalog only returns available providers. Querying an uninstalled optional family does not fail server startup.

## Dependencies

- `nlalpha-core`: provides the `CapabilityPluginRegistry` and `ProviderManifest` contracts.
- `mcp>=1.6.0`: MCP server runtime.

## Installation

```bash
pip install nlalpha-capability
```

## Running

```bash
NLALPHA_HOST=127.0.0.1 NLALPHA_PORT=8000 python -m nlalpha_capability.server
```

Or via the stdio transport:

```bash
python -c "from nlalpha_capability.server import main; main()"
```

DNS-rebinding protection allows only localhost/loopback by default. When a container or gateway uses another host, list the hosts explicitly through `NLALPHA_ALLOWED_HOSTS`; do not use wildcards.

## Focused verification

The capability discovery suite passed 26 tests and 37 subtests, with 1 warning, in 3.76 seconds. This verifies the focused capability cases only; it is not a full release-gate result.

## Self-description

`about(sections=None)` reports the service catalog and discovery diagnostics. `confess(provider_id, sections=None)` describes the cached provider manifest, declared methods, helper entries, and optional declared guidance. Reuse a complete description while its SHA-256 revision is unchanged and request selected sections when only part is needed. A missing required description document is an explicit discovery error; no synthetic helper is created to fill an absent optional provider.

## Description revisions

`about` and provider `confess` use `nlalpha.description.v1` and derive their content from the cached discovery records, installed package metadata, provider manifest, declared methods, helper records, and packaged resources. Selected sections and complete documents carry the same canonical `description_revision`. The available catalog includes only providers that are actually available; diagnostics describe installed or registered providers that cannot load. Missing optional providers do not create synthetic catalog entries.

## License

`nlalpha-capability` is a community distribution under AGPL-3.0-or-later. Private enhancement packages and third-party dependencies retain their own licenses.

## Container image

The community image is built with this package's Dockerfile and installs a non-editable wheel closure on Python 3.12 slim. It runs this service's MCP entry point.
