Metadata-Version: 2.4
Name: nodus-mcp
Version: 0.1.0
Summary: MCP (Model Context Protocol) library for Nodus — bidirectional client + server
Author: Shawn Knight
License: MIT License
        
        Copyright (c) 2026 Masterplanner25
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Masterplanner25/nodus-mcp
Project-URL: Repository, https://github.com/Masterplanner25/nodus-mcp
Project-URL: Changelog, https://github.com/Masterplanner25/nodus-mcp/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nodus-lang<5.0.0,>=4.0.0
Requires-Dist: httpx>=0.24.0
Dynamic: license-file

# nodus-mcp

Model Context Protocol (MCP) library for [Nodus](https://github.com/Masterplanner25/Nodus)
— bidirectional client and server, implementing the 2026-07-28 RC specification.

**Status: v0.1.0 prepared, not yet published.** Waiting for the coordinated launch
with nodus-lang 4.0.0 and nodus-a2a v0.1.0. Two of three artifacts are ready.

---

## Authentication warning

**v0.1 does not support OAuth 2.0.** Only bearer-token authentication is implemented.
Servers that require OAuth 2.0 / OIDC authentication (including many production MCP
deployments) cannot be used with nodus-mcp v0.1. OAuth support is planned for v0.2.

To connect to a server with a bearer token:
```python
from nodus_mcp import HttpTransport, McpClient

client = McpClient()
transport = HttpTransport("https://server/mcp", bearer_token="sk-...")
conn = client.connect(transport, alias="srv")
```

---

## Installation

```bash
# Once nodus-lang 4.0.0 is on PyPI:
pip install nodus-mcp

# Development install (both repos checked out):
pip install -e . --no-deps
# Set PYTHONPATH to nodus-lang source:
# PYTHONPATH="path/to/nodus-lang/src" python ...
```

---

## Quick start

### Run an MCP server

```bash
# Spawned-child stdio mode (parent process connects to our stdin/stdout)
nodus-mcp serve --stdio

# HTTP mode
nodus-mcp serve --http --port 8080 --bearer-token my-api-key
```

To expose tools, use the Python API before serving:

```python
from nodus_mcp import McpServer, HttpServerTransport

server = McpServer()
server.set_resource_list_handler(lambda: [
    {"uri": "file:///data", "name": "Data Directory"}
])

transport = HttpServerTransport("localhost", 8080)
transport.serve(server.dispatch)
```

### Connect to a server

```bash
nodus-mcp connect http://localhost:8080 --bearer-token my-api-key
```

Interactive REPL:
```
Connected. Server: my-server 1.0. Tools: 3. Type 'help' for commands.
mcp> list
  my.tool — Does something useful
mcp> call my.tool {"x": 42}
{"content": [{"type": "text", "text": "done"}]}
mcp> quit
```

### Use from a Nodus script

```nodus
import "nodus-mcp"

// Discover and call tools (requires McpClient.connect() in host Python code)
let result = tool.invoke("mcp.srv.my_tool", {x: 42})
```

---

## Entry-point contract

```python
# nodus-mcp registers itself in the nodus.nd entry-point group:
# nodus-mcp = "nodus_mcp.nd:get_nd_root"
#
# After pip install nodus-mcp, any Nodus script can:
#   import "nodus-mcp"
# and get the adapter module without additional configuration.
# See docs/guide/library-entry-points.md in nodus-lang for the contract.
```

---

## Deprecated features (Roots + Sampling)

nodus-mcp v0.1 includes Roots and Sampling despite their deprecation in the
2026-07-28 RC, because existing MCP servers in the ecosystem use them (real
interop need) and the RC's 12-month deprecation window extends to at least
2027-07-28.

**Do not remove Roots or Sampling before:**
1. The protocol has actually removed them, AND
2. nodus-mcp has shipped a replacement

The removal gate is 2027-07-28 at the earliest. See `docs/governance/TECH_DEBT.md`
(TD-001, TD-002) and `docs/design/05-deprecated-features.md §C1`.

---

## Known limitations

| Limitation | Details |
|---|---|
| No OAuth support | Bearer token only; see auth warning above |
| `resources/subscribe` not implemented | Server-push deferred to v0.2 |
| Server-initiated requests (HTTP) | `roots/list`, `sampling/createMessage`, `elicitation/create` are stdio-only; HTTP has no push channel (TD-007) |
| Partial JSON Schema validation | `_validate_args` checks required fields and primitive types; `enum`, `pattern`, `minLength` etc. are not enforced server-side (TD-008) |
| Resource handler `KeyError` convention | Resource read handlers must raise `KeyError(uri)` for unknown URIs (TD-009) |
| `requestState` is on the wire | Server-issued elicitation state travels to the client; never checkpoint secrets (TD-010) |

---

## Spec target

[2026-07-28 RC](https://spec.modelcontextprotocol.io/) — stateless (no session
initialization handshake, no `Mcp-Session-Id`). Capabilities travel in `_meta`
per-request. `server/discover` replaces capability exchange.
