mcpatom 0.1.0__tar.gz

mcpatom-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check
+      - run: uv run pytest

mcpatom-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing authenticates via OIDC, no token
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
+      - run: uv build
+      - run: uv publish --trusted-publishing always

mcpatom-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/

mcpatom-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

mcpatom-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Mitch
+
+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.

mcpatom-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: mcpatom
+Version: 0.1.0
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mcpatom
+
+A minimal Python [MCP](https://modelcontextprotocol.io) Server SDK.
+
+From Greek *atomos*: indivisible. The whole library is a single file,
+`mcpatom.py`, consumable two ways:
+
+- **Copy the file** into your project. No dependency, no lockfile entry.
+- **Install the package**: `pip install mcpatom` - the file itself is
+  the installed module.
+
+## Scope
+
+- Tools, resources, and prompts, over stdio or streamable HTTP.
+- Protocol versions `2025-06-18` and `2025-11-25`.
+- stdlib-only Python >= 3.10, no dependencies, ever.
+
+Everything else (sampling, elicitation, subscriptions, auth, etc.) is deliberately omitted.
+
+## Usage
+
+```python
+from mcpatom import Server
+
+srv = Server("my-server")
+
+
+@srv.tool
+def greet(name: str, excited: bool = False) -> str:
+    """Return a greeting for the given name."""
+    return f"Hello, {name}{'!' if excited else '.'}"
+
+
+@srv.resource("data://motd")
+def motd() -> str:
+    """Message of the day."""
+    return "Be indivisible."
+
+
+@srv.prompt
+def haiku(topic: str) -> str:
+    """Ask for a haiku."""
+    return f"Write a haiku about {topic}."
+
+
+srv.serve_stdio()
+```
+
+For streamable HTTP instead of stdio, end with:
+
+```python
+srv.serve_http(8388)  # http://127.0.0.1:8388/mcp
+```
+
+`serve_http` binds to loopback and rejects DNS-rebinding requests;
+`host="0.0.0.0"` widens the bind and switches those checks off.
+
+More runnable servers in [examples/](examples/).
+
+## Schemas and return types
+
+Each function's name, docstring, and annotations become the tool's name,
+description, and schema; `@srv.tool(name=, description=, input_schema=,
+output_schema=)` override generation, and `extra=` merges raw fields into
+the listing. `Server()` also takes `version=` and `instructions=`.
+Parameters may be annotated with any of these:
+- `str`
+- `int`
+- `float`
+- `bool`
+- `list[X]` (or bare `list`)
+- `Literal[...]`
+- `TypedDict`
+- `X | None` of any of the above
+
+`Annotated[X, "text"]` adds a description the model sees.
+
+A tool may return:
+
+- `str` - one text block
+- `dict` - JSON text plus `structuredContent`; a `TypedDict` return
+  annotation publishes the matching `outputSchema`
+- `Image(data, mime_type)` / `Audio(data, mime_type)` - one binary
+  block (raw bytes in, base64 on the wire)
+- a tuple - one block per item: `str` text, `Image`/`Audio` media, a
+  dict whose `"type"` names a spec block type verbatim (e.g.
+  `resource_link`)
+- `None` - empty content; any other JSON value - text
+
+Raising is the error API: any exception becomes `isError` content the
+model can read and correct.
+
+Resources return `str` (text) or `bytes` (base64 blob).
+
+Prompts take only `str` arguments and return a `str` user message, or a
+list of message dicts passed through verbatim.
+
+## Wiring it up
+
+```sh
+claude mcp add my-server -- /abs/path/.venv/bin/python /abs/path/server.py
+```
+
+or in any `mcpServers` config:
+
+```json
+{"mcpServers": {"my-server": {"command": "/abs/path/.venv/bin/python", "args": ["/abs/path/server.py"]}}}
+```
+
+Smoke test without a client:
+
+```sh
+echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | python server.py
+# {"jsonrpc":"2.0","id":1,"result":{}}
+```
+

mcpatom-0.1.0/README.md

@@ -0,0 +1,116 @@
+# mcpatom
+
+A minimal Python [MCP](https://modelcontextprotocol.io) Server SDK.
+
+From Greek *atomos*: indivisible. The whole library is a single file,
+`mcpatom.py`, consumable two ways:
+
+- **Copy the file** into your project. No dependency, no lockfile entry.
+- **Install the package**: `pip install mcpatom` - the file itself is
+  the installed module.
+
+## Scope
+
+- Tools, resources, and prompts, over stdio or streamable HTTP.
+- Protocol versions `2025-06-18` and `2025-11-25`.
+- stdlib-only Python >= 3.10, no dependencies, ever.
+
+Everything else (sampling, elicitation, subscriptions, auth, etc.) is deliberately omitted.
+
+## Usage
+
+```python
+from mcpatom import Server
+
+srv = Server("my-server")
+
+
+@srv.tool
+def greet(name: str, excited: bool = False) -> str:
+    """Return a greeting for the given name."""
+    return f"Hello, {name}{'!' if excited else '.'}"
+
+
+@srv.resource("data://motd")
+def motd() -> str:
+    """Message of the day."""
+    return "Be indivisible."
+
+
+@srv.prompt
+def haiku(topic: str) -> str:
+    """Ask for a haiku."""
+    return f"Write a haiku about {topic}."
+
+
+srv.serve_stdio()
+```
+
+For streamable HTTP instead of stdio, end with:
+
+```python
+srv.serve_http(8388)  # http://127.0.0.1:8388/mcp
+```
+
+`serve_http` binds to loopback and rejects DNS-rebinding requests;
+`host="0.0.0.0"` widens the bind and switches those checks off.
+
+More runnable servers in [examples/](examples/).
+
+## Schemas and return types
+
+Each function's name, docstring, and annotations become the tool's name,
+description, and schema; `@srv.tool(name=, description=, input_schema=,
+output_schema=)` override generation, and `extra=` merges raw fields into
+the listing. `Server()` also takes `version=` and `instructions=`.
+Parameters may be annotated with any of these:
+- `str`
+- `int`
+- `float`
+- `bool`
+- `list[X]` (or bare `list`)
+- `Literal[...]`
+- `TypedDict`
+- `X | None` of any of the above
+
+`Annotated[X, "text"]` adds a description the model sees.
+
+A tool may return:
+
+- `str` - one text block
+- `dict` - JSON text plus `structuredContent`; a `TypedDict` return
+  annotation publishes the matching `outputSchema`
+- `Image(data, mime_type)` / `Audio(data, mime_type)` - one binary
+  block (raw bytes in, base64 on the wire)
+- a tuple - one block per item: `str` text, `Image`/`Audio` media, a
+  dict whose `"type"` names a spec block type verbatim (e.g.
+  `resource_link`)
+- `None` - empty content; any other JSON value - text
+
+Raising is the error API: any exception becomes `isError` content the
+model can read and correct.
+
+Resources return `str` (text) or `bytes` (base64 blob).
+
+Prompts take only `str` arguments and return a `str` user message, or a
+list of message dicts passed through verbatim.
+
+## Wiring it up
+
+```sh
+claude mcp add my-server -- /abs/path/.venv/bin/python /abs/path/server.py
+```
+
+or in any `mcpServers` config:
+
+```json
+{"mcpServers": {"my-server": {"command": "/abs/path/.venv/bin/python", "args": ["/abs/path/server.py"]}}}
+```
+
+Smoke test without a client:
+
+```sh
+echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | python server.py
+# {"jsonrpc":"2.0","id":1,"result":{}}
+```
+

mcpatom-0.1.0/examples/README.md

@@ -0,0 +1,33 @@
+# Examples
+
+Each file is a complete server. Run from the repo root:
+
+```sh
+python -m examples.tools
+```
+
+or copy `mcpatom.py` next to the example and run it directly.
+
+- `tools.py` - typed parameters, a structured (dict) return, an image
+  return, and hand-written schema overrides
+- `resources.py` - a text resource and a dict served as JSON
+- `prompts.py` - a string prompt and a multi-message prompt
+- `streamable_http.py` - the same idea over streamable HTTP
+
+Smoke test a stdio example by piping a request in:
+
+```sh
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python -m examples.tools
+```
+
+For `streamable_http.py`, start it, then:
+
+```sh
+curl -s localhost:8388/mcp -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
+```
+
+Or lend one to Claude Code for a single session:
+
+```sh
+claude --mcp-config '{"mcpServers":{"ex":{"command":"python","args":["-m","examples.tools"]}}}'
+```

mcpatom-0.1.0/examples/prompts.py

@@ -0,0 +1,23 @@
+"""Prompts: a plain string reply and a multi-message conversation."""
+
+from mcpatom import Server
+
+srv = Server("prompts-example")
+
+
+@srv.prompt
+def haiku(topic: str) -> str:
+    """Ask for a haiku."""
+    return f"Write a haiku about {topic}."
+
+
+@srv.prompt
+def review(code: str) -> list:
+    """Review code, priming the assistant's opening."""
+    return [
+        {"role": "user", "content": {"type": "text", "text": f"Review this code:\n{code}"}},
+        {"role": "assistant", "content": {"type": "text", "text": "Three issues, most severe first:"}},
+    ]
+
+
+srv.serve_stdio()

mcpatom-0.1.0/examples/resources.py

@@ -0,0 +1,20 @@
+"""Resources: a plain text read and a dict served as JSON."""
+
+from mcpatom import Server
+
+srv = Server("resources-example")
+
+
+@srv.resource("data://motd")
+def motd() -> str:
+    """Message of the day."""
+    return "Be indivisible."
+
+
+@srv.resource("data://config", mime_type="application/json")
+def config() -> dict:
+    """Server configuration."""
+    return {"theme": "dark", "retries": 3}  # dicts are serialised to JSON text
+
+
+srv.serve_stdio()

mcpatom-0.1.0/examples/streamable_http.py

@@ -0,0 +1,14 @@
+"""A greeter served over streamable HTTP instead of stdio."""
+
+from mcpatom import Server
+
+srv = Server("http-example")
+
+
+@srv.tool
+def greet(name: str) -> str:
+    """Return a greeting for the given name."""
+    return f"Hello, {name}."
+
+
+srv.serve_http(8388)  # POST http://127.0.0.1:8388/mcp

mcpatom-0.1.0/examples/tools.py

@@ -0,0 +1,48 @@
+"""Tools: typed parameters, a structured (dict) return, an image return, and
+hand-written schema overrides."""
+
+import random
+from pathlib import Path
+from typing import Annotated, Literal
+
+from mcpatom import Image, Server
+
+srv = Server("tools-example")
+
+
+@srv.tool
+def add(a: float, b: float) -> str:
+    """Add two numbers."""
+    return str(a + b)
+
+
+@srv.tool
+def roll(sides: Annotated[Literal[6, 20], "Die size"] = 6) -> dict:
+    """Roll a die."""
+    return {"sides": sides, "value": random.randint(1, sides)}
+
+
+@srv.tool(
+    input_schema={
+        "type": "object",
+        "properties": {"celsius": {"type": "number", "minimum": -273.15}},
+        "required": ["celsius"],
+    },
+    output_schema={
+        "type": "object",
+        "properties": {"fahrenheit": {"type": "number"}},
+        "required": ["fahrenheit"],
+    },
+)
+def convert(celsius: float) -> dict:
+    """Convert Celsius to Fahrenheit."""
+    return {"fahrenheit": celsius * 9 / 5 + 32}
+
+
+@srv.tool
+def image() -> Image:
+    """A mystery image."""
+    return Image(Path(__file__).with_name("cat.gif").read_bytes(), "image/gif")
+
+
+srv.serve_stdio()