harnessapi 0.1.0__py3-none-any.whl

harnessapi/__init__.py

@@ -0,0 +1,27 @@
+from .app import HarnessAPI
+from .decorators import skill
+from .exceptions import (
+    EditNotAllowedError,
+    SkillAPIError,
+    SkillConflictError,
+    SkillHandlerError,
+    SkillNotFoundError,
+    SkillValidationError,
+)
+from .models import SkillInput, SkillOutput
+from .skill import Skill, SkillMeta
+
+__all__ = [
+    "HarnessAPI",
+    "Skill",
+    "SkillMeta",
+    "SkillInput",
+    "SkillOutput",
+    "skill",
+    "SkillAPIError",
+    "SkillNotFoundError",
+    "SkillValidationError",
+    "SkillConflictError",
+    "SkillHandlerError",
+    "EditNotAllowedError",
+]

harnessapi/app.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+
+from .decorators import get_registered_skills
+from .discovery import SkillsDirectoryProvider
+from .exceptions import SkillConflictError
+from .mcp import build_mcp_server, register_skill_as_mcp_tool
+from .routing import EditRoute, SkillRoute
+from .skill import Skill
+
+
+class HarnessAPI(FastAPI):
+    """FastAPI subclass that auto-discovers skills and exposes them as HTTP + MCP."""
+
+    def __init__(
+        self,
+        *,
+        skills_dir: str | Path | None = None,
+        mcp_path: str = "/mcp",
+        mcp_server_name: str = "HarnessAPI",
+        enable_edit_endpoints: bool = False,
+        **fastapi_kwargs: Any,
+    ) -> None:
+        self._mcp = build_mcp_server(mcp_server_name)
+        self._skills: dict[str, Skill] = {}
+        self._mcp_path = mcp_path
+        self._enable_edit = enable_edit_endpoints
+
+        mcp_app = self._mcp.http_app(path="/")
+        user_lifespan = fastapi_kwargs.pop("lifespan", None)
+
+        @asynccontextmanager
+        async def merged_lifespan(app):
+            async with mcp_app.lifespan(mcp_app):
+                if user_lifespan is not None:
+                    async with user_lifespan(app):
+                        yield
+                else:
+                    yield
+
+        super().__init__(lifespan=merged_lifespan, **fastapi_kwargs)
+
+        # Folder-based discovery
+        if skills_dir is not None:
+            for skill in SkillsDirectoryProvider(skills_dir).discover():
+                self._register_skill(skill)
+
+        # Decorator-based skills
+        for skill in get_registered_skills():
+            if skill.meta.name not in self._skills:
+                self._register_skill(skill)
+
+        # Mount FastMCP ASGI app
+        self.mount(mcp_path, mcp_app)
+
+    # ------------------------------------------------------------------
+    def _register_skill(self, skill: Skill) -> None:
+        name = skill.meta.name
+        if name in self._skills:
+            raise SkillConflictError(f"Skill '{name}' is already registered")
+        self._skills[name] = skill
+        self.router.routes.append(SkillRoute(skill))
+        if self._enable_edit:
+            self.router.routes.append(EditRoute(skill))
+        register_skill_as_mcp_tool(self._mcp, skill)
+
+    def add_skill(self, skill: Skill) -> None:
+        """Programmatically register a skill after startup."""
+        self._register_skill(skill)
+
+    @property
+    def skills(self) -> dict[str, Skill]:
+        return dict(self._skills)

harnessapi/decorators.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import functools
+from typing import Callable
+
+from .models import SkillInput, SkillOutput
+from .skill import Skill, SkillMeta
+
+_registry: dict[str, Skill] = {}
+
+
+def skill(
+    name: str | None = None,
+    *,
+    description: str | None = None,
+    is_mcp: bool = True,
+    tags: list[str] | None = None,
+    timeout_secs: float | None = 30.0,
+    input_model: type[SkillInput] | None = None,
+    output_model: type[SkillOutput] | None = None,
+) -> Callable:
+    """Decorator to register a skill without a folder.
+
+    Usage::
+
+        @skill(name="greet", input_model=GreetInput, output_model=GreetOutput)
+        async def greet(input: GreetInput) -> GreetOutput: ...
+    """
+    def decorator(fn: Callable) -> Callable:
+        skill_name = name or fn.__name__
+        in_model = input_model
+        out_model = output_model
+
+        if in_model is None or out_model is None:
+            hints = getattr(fn, "__annotations__", {})
+            if in_model is None:
+                in_model = hints.get("input") or hints.get("return")
+            if out_model is None:
+                out_model = hints.get("return")
+
+        if in_model is None or out_model is None:
+            raise TypeError(
+                f"@skill('{skill_name}'): provide input_model and output_model, "
+                "or annotate the function with Input and return types."
+            )
+
+        meta = SkillMeta(
+            name=skill_name,
+            description=description or fn.__doc__ or "",
+            is_mcp=is_mcp,
+            tags=tags or [],
+            timeout_secs=timeout_secs,
+        )
+        s = Skill(
+            meta=meta,
+            input_model=in_model,
+            output_model=out_model,
+            handler=fn,
+            edit_handler=None,
+            folder=None,
+        )
+        _registry[skill_name] = s
+
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            return await fn(*args, **kwargs)
+
+        wrapper.__skill__ = s  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator
+
+
+def get_registered_skills() -> list[Skill]:
+    return list(_registry.values())

harnessapi/discovery.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import ast
+import importlib.util
+import json
+import tomllib
+import types
+from pathlib import Path
+from typing import Iterator
+
+from .models import SkillInput, SkillOutput
+from .skill import Skill, SkillMeta
+
+
+class SkillsDirectoryProvider:
+    """Scans a directory tree and yields a Skill for each valid skill folder."""
+
+    def __init__(self, root: Path | str) -> None:
+        self.root = Path(root)
+
+    def discover(self) -> Iterator[Skill]:
+        for folder in sorted(self.root.iterdir()):
+            if folder.is_dir() and not folder.name.startswith("_"):
+                skill = self._load_skill(folder)
+                if skill is not None:
+                    yield skill
+
+    # ------------------------------------------------------------------
+    def _load_skill(self, folder: Path) -> Skill | None:
+        handler_path = folder / "handler.py"
+        models_path = folder / "models.py"
+        if not handler_path.exists() or not models_path.exists():
+            return None
+
+        meta = self._load_meta(folder)
+        pkg = self._make_package(folder)
+        models_mod = self._load_module(models_path, f"{pkg.__name__}.models", pkg)
+        handler_mod = self._load_module(handler_path, f"{pkg.__name__}.handler", pkg)
+
+        input_model = getattr(models_mod, "Input", None)
+        output_model = getattr(models_mod, "Output", None)
+        if input_model is None or output_model is None:
+            raise TypeError(
+                f"Skill '{folder.name}': models.py must define Input and Output classes"
+            )
+        if not issubclass(input_model, SkillInput):
+            raise TypeError(
+                f"Skill '{folder.name}': Input must subclass SkillInput"
+            )
+        if not issubclass(output_model, SkillOutput):
+            raise TypeError(
+                f"Skill '{folder.name}': Output must subclass SkillOutput"
+            )
+
+        handle_fn = getattr(handler_mod, "handle", None)
+        if handle_fn is None:
+            raise TypeError(
+                f"Skill '{folder.name}': handler.py must define a 'handle' function"
+            )
+
+        return Skill(
+            meta=meta,
+            input_model=input_model,
+            output_model=output_model,
+            handler=handle_fn,
+            edit_handler=self._load_edit_handler(folder, pkg),
+            folder=folder,
+            examples=self._load_examples(folder),
+            defaults=self._load_defaults(folder),
+        )
+
+    @staticmethod
+    def _make_package(folder: Path) -> types.ModuleType:
+        """Create a synthetic package namespace for a skill folder."""
+        import sys
+        pkg_name = f"_harnessapi_skill_{folder.name}"
+        if pkg_name in sys.modules:
+            return sys.modules[pkg_name]
+        pkg = types.ModuleType(pkg_name)
+        pkg.__path__ = [str(folder)]  # type: ignore[assignment]
+        pkg.__package__ = pkg_name
+        pkg.__spec__ = None  # type: ignore[assignment]
+        sys.modules[pkg_name] = pkg
+        return pkg
+
+    def _load_meta(self, folder: Path) -> SkillMeta:
+        toml_path = folder / "skill.toml"
+        data: dict = {}
+        if toml_path.exists():
+            with toml_path.open("rb") as f:
+                raw = tomllib.load(f)
+            data = raw.get("skill", {})
+        handler_path = folder / "handler.py"
+        description = data.get("description") or _extract_docstring(handler_path) or ""
+        return SkillMeta(
+            name=data.get("name", folder.name),
+            description=description,
+            is_mcp=data.get("is_mcp", True),
+            tags=data.get("tags", []),
+            timeout_secs=data.get("timeout_secs", 30.0),
+        )
+
+    @staticmethod
+    def _load_module(
+        path: Path, module_name: str, package: types.ModuleType | None = None
+    ) -> types.ModuleType:
+        spec = importlib.util.spec_from_file_location(
+            module_name,
+            path,
+            submodule_search_locations=[],
+        )
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load module from {path}")
+        module = importlib.util.module_from_spec(spec)
+        if package is not None:
+            module.__package__ = package.__name__
+        import sys
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+        return module
+
+    def _load_edit_handler(self, folder: Path, pkg: types.ModuleType | None = None):
+        edit_path = folder / "edit" / "handler.py"
+        if not edit_path.exists():
+            return None
+        mod = self._load_module(edit_path, f"_skill_{folder.name}_edit", pkg)
+        return getattr(mod, "handle", None)
+
+    @staticmethod
+    def _load_examples(folder: Path) -> list[dict]:
+        examples_dir = folder / "examples"
+        if not examples_dir.exists():
+            return []
+        return [
+            json.loads(f.read_text())
+            for f in sorted(examples_dir.glob("*.json"))
+        ]
+
+    @staticmethod
+    def _load_defaults(folder: Path) -> dict | None:
+        p = folder / "defaults" / "input.json"
+        return json.loads(p.read_text()) if p.exists() else None
+
+
+def _extract_docstring(path: Path) -> str | None:
+    try:
+        tree = ast.parse(path.read_text())
+        return ast.get_docstring(tree)
+    except Exception:
+        return None

harnessapi/edit.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import textwrap
+import types
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from .skill import Skill
+
+
+class EditRequest(BaseModel):
+    source_code: str
+    persist: bool = False
+
+
+class EditResponse(BaseModel):
+    status: str
+    skill_name: str
+    error: str | None = None
+
+
+def apply_edit(skill: Skill, request: EditRequest) -> None:
+    """Compile source_code and hot-swap skill.edit_handler.
+
+    Executes arbitrary Python — only expose this endpoint with auth in production.
+    """
+    source = textwrap.dedent(request.source_code)
+    module = types.ModuleType(f"_skill_{skill.meta.name}_edit_runtime")
+    try:
+        exec(compile(source, "<edit>", "exec"), module.__dict__)
+    except SyntaxError as exc:
+        raise ValueError(f"Syntax error in submitted handler: {exc}") from exc
+
+    handle_fn = getattr(module, "handle", None)
+    if handle_fn is None:
+        raise ValueError("Submitted source must define a `handle` function")
+
+    skill.edit_handler = handle_fn
+
+    if request.persist and skill.folder is not None:
+        edit_dir = skill.folder / "edit"
+        edit_dir.mkdir(exist_ok=True)
+        (edit_dir / "handler.py").write_text(request.source_code)

harnessapi/exceptions.py

@@ -0,0 +1,22 @@
+class SkillAPIError(Exception):
+    """Base exception for all harnessapi errors."""
+
+
+class SkillNotFoundError(SkillAPIError):
+    """Raised when a skill name cannot be resolved."""
+
+
+class SkillValidationError(SkillAPIError):
+    """Raised when input validation fails against the skill's input model."""
+
+
+class SkillConflictError(SkillAPIError):
+    """Raised when two skills with the same name are registered."""
+
+
+class SkillHandlerError(SkillAPIError):
+    """Raised when a skill handler raises an unexpected exception."""
+
+
+class EditNotAllowedError(SkillAPIError):
+    """Raised when an edit is attempted but the endpoint is disabled."""

harnessapi/mcp.py

@@ -0,0 +1,58 @@
+import asyncio
+from typing import Any
+
+from fastmcp import FastMCP
+
+from .skill import Skill
+
+
+def build_mcp_server(name: str = "HarnessAPI") -> FastMCP:
+    return FastMCP(name=name)
+
+
+def register_skill_as_mcp_tool(mcp: FastMCP, skill: Skill) -> None:
+    if not skill.meta.is_mcp:
+        return
+
+    _make_and_register(mcp, skill)
+
+
+def _make_and_register(mcp: FastMCP, skill: Skill) -> None:
+    input_model = skill.input_model
+    is_streaming = skill.is_streaming_handler()
+    handler = skill.effective_handler
+    skill_name = skill.meta.name
+    skill_desc = skill.meta.description
+    timeout = skill.meta.timeout_secs
+
+    # Build the wrapper source so the annotation resolves at definition time.
+    # FastMCP 3.x inspects __annotations__ — the model must be in the function's
+    # global namespace, not just the enclosing scope.
+    globs = {
+        "asyncio": asyncio,
+        "Any": Any,
+        "input_model": input_model,
+        "handler": handler,
+        "is_streaming": is_streaming,
+        "timeout": timeout,
+    }
+    src = (
+        "async def mcp_wrapper(input: input_model) -> Any:\n"
+        "    if is_streaming:\n"
+        "        chunks = []\n"
+        "        async for chunk in handler(input):\n"
+        "            chunks.append(str(chunk))\n"
+        "        return '\\n'.join(chunks)\n"
+        "    else:\n"
+        "        if timeout is not None:\n"
+        "            result = await asyncio.wait_for(handler(input), timeout=timeout)\n"
+        "        else:\n"
+        "            result = await handler(input)\n"
+        "        return result.model_dump()\n"
+    )
+    exec(compile(src, "<mcp_wrapper>", "exec"), globs)
+    mcp_wrapper = globs["mcp_wrapper"]
+    mcp_wrapper.__name__ = skill_name
+    mcp_wrapper.__doc__ = skill_desc
+
+    mcp.tool(name=skill_name, description=skill_desc)(mcp_wrapper)

harnessapi/models.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class SkillInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class SkillOutput(BaseModel):
+    model_config = ConfigDict(extra="forbid")

harnessapi/routing.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from fastapi.routing import APIRoute
+
+from .edit import EditRequest, EditResponse, apply_edit
+from .streaming import make_sse_response
+
+if TYPE_CHECKING:
+    from .skill import Skill
+
+
+class SkillRoute(APIRoute):
+    """POST /skills/{name} — SSE by default, JSON when Accept: application/json."""
+
+    def __init__(self, skill: Skill, **kwargs) -> None:
+        self._skill = skill
+        endpoint = self._make_endpoint()
+        super().__init__(
+            path=f"/skills/{skill.meta.name}",
+            endpoint=endpoint,
+            methods=["POST"],
+            tags=skill.meta.tags or ["skills"],
+            summary=skill.meta.name,
+            description=skill.meta.description,
+            **kwargs,
+        )
+
+    def _make_endpoint(self):
+        skill = self._skill
+
+        async def endpoint(request: Request):
+            body = await request.json()
+            input_obj = skill.input_model.model_validate(body)
+            accept = request.headers.get("accept", "")
+            if "application/json" in accept:
+                if skill.is_streaming_handler():
+                    chunks: list[str] = []
+                    async for chunk in skill.effective_handler(input_obj):
+                        chunks.append(str(chunk))
+                    return JSONResponse(content={"chunks": chunks})
+                else:
+                    import asyncio
+                    timeout = skill.meta.timeout_secs
+                    if timeout is not None:
+                        result = await asyncio.wait_for(
+                            skill.effective_handler(input_obj), timeout=timeout
+                        )
+                    else:
+                        result = await skill.effective_handler(input_obj)
+                    return JSONResponse(content=result.model_dump())
+            return make_sse_response(skill, input_obj)
+
+        endpoint.__name__ = f"skill_{skill.meta.name}"
+        return endpoint
+
+
+class EditRoute(APIRoute):
+    """POST /skills/{name}/edit — hot-swap the skill handler."""
+
+    def __init__(self, skill: Skill, **kwargs) -> None:
+        self._skill = skill
+        endpoint = self._make_endpoint()
+        super().__init__(
+            path=f"/skills/{skill.meta.name}/edit",
+            endpoint=endpoint,
+            methods=["POST"],
+            tags=["skills", "edit"],
+            summary=f"Edit handler: {skill.meta.name}",
+            response_model=EditResponse,
+            **kwargs,
+        )
+
+    def _make_endpoint(self):
+        skill = self._skill
+
+        async def endpoint(body: EditRequest) -> EditResponse:
+            try:
+                apply_edit(skill, body)
+                return EditResponse(status="ok", skill_name=skill.meta.name)
+            except ValueError as exc:
+                return EditResponse(status="error", skill_name=skill.meta.name, error=str(exc))
+
+        endpoint.__name__ = f"edit_{skill.meta.name}"
+        return endpoint

harnessapi/skill.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from .models import SkillInput, SkillOutput
+
+
+@dataclass
+class SkillMeta:
+    name: str
+    description: str
+    is_mcp: bool = True
+    tags: list[str] = field(default_factory=list)
+    timeout_secs: float | None = 30.0
+
+
+@dataclass
+class Skill:
+    meta: SkillMeta
+    input_model: type[SkillInput]
+    output_model: type[SkillOutput]
+    handler: Callable
+    edit_handler: Callable | None
+    folder: Path | None
+    examples: list[dict[str, Any]] = field(default_factory=list)
+    defaults: dict[str, Any] | None = None
+
+    @property
+    def effective_handler(self) -> Callable:
+        return self.edit_handler if self.edit_handler is not None else self.handler
+
+    def is_streaming_handler(self) -> bool:
+        return inspect.isasyncgenfunction(self.effective_handler)

harnessapi/streaming.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING
+
+from sse_starlette.sse import EventSourceResponse, ServerSentEvent
+
+if TYPE_CHECKING:
+    from .skill import Skill
+    from .models import SkillInput
+
+
+async def skill_sse_generator(
+    skill: Skill,
+    input_obj: SkillInput,
+) -> AsyncGenerator[ServerSentEvent, None]:
+    handler = skill.effective_handler
+    timeout = skill.meta.timeout_secs
+    try:
+        if skill.is_streaming_handler():
+            async def _stream():
+                async for chunk in handler(input_obj):
+                    yield ServerSentEvent(data=str(chunk), event="chunk")
+                yield ServerSentEvent(data="", event="done")
+
+            async for event in _stream():
+                yield event
+        else:
+            if timeout is not None:
+                result = await asyncio.wait_for(handler(input_obj), timeout=timeout)
+            else:
+                result = await handler(input_obj)
+            yield ServerSentEvent(data=result.model_dump_json(), event="result")
+            yield ServerSentEvent(data="", event="done")
+    except asyncio.TimeoutError:
+        yield ServerSentEvent(data=f"Skill '{skill.meta.name}' timed out", event="error")
+    except Exception as exc:
+        yield ServerSentEvent(data=str(exc), event="error")
+
+
+def make_sse_response(skill: Skill, input_obj: SkillInput) -> EventSourceResponse:
+    return EventSourceResponse(skill_sse_generator(skill, input_obj))

harnessapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: harnessapi
+Version: 0.1.0
+Summary: Skill-first API framework: every endpoint is also an MCP tool
+License-File: LICENSE
+Keywords: agents,fastapi,llm,mcp,skills,sse,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: sse-starlette>=2.0.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# harnessapi
+
+**Skill-first API framework** — define a skill once, get both an HTTP endpoint and an MCP tool automatically.
+
+Every skill is a folder. Drop in a `handler.py` and `models.py` and you have:
+- `POST /skills/{name}` — streaming SSE by default, JSON on request
+- An MCP tool at `/mcp` — ready for Claude Desktop, Cursor, or any MCP client
+
+---
+
+## Install
+
+```bash
+uv add harnessapi
+```
+
+Or clone and run locally:
+
+```bash
+git clone <repo>
+cd harnessapi
+uv sync
+```
+
+---
+
+## Quickstart
+
+Create your skill folder:
+
+```
+my_project/
+├── main.py
+└── skills/
+    └── greet/
+        ├── models.py
+        └── handler.py
+```
+
+**`skills/greet/models.py`**
+```python
+from harnessapi import SkillInput, SkillOutput
+
+class Input(SkillInput):
+    name: str
+
+class Output(SkillOutput):
+    message: str
+```
+
+**`skills/greet/handler.py`**
+```python
+"""Say hello to someone."""
+from .models import Input, Output
+
+async def handle(input: Input) -> Output:
+    return Output(message=f"Hello, {input.name}!")
+```
+
+**`main.py`**
+```python
+from pathlib import Path
+from harnessapi import HarnessAPI
+
+app = HarnessAPI(skills_dir=Path(__file__).parent / "skills")
+```
+
+Run it exactly like a FastAPI app:
+
+```bash
+uvicorn main:app --reload
+```
+
+---
+
+## Try the factorial example
+
+The repo ships with a streaming factorial skill that demonstrates SSE + MCP together.
+
+```bash
+# from the repo root
+uv run uvicorn examples.factorial_app.main:app --reload
+```
+
+### Call via HTTP — SSE stream (default)
+
+```bash
+curl -X POST http://localhost:8000/skills/factorial \
+  -H "Content-Type: application/json" \
+  -d '{"n": 5}'
+```
+
+Response (each multiplication step streamed as it's computed):
+
+```
+event: chunk
+data: start: 1
+
+event: chunk
+data: 2: 2
+
+event: chunk
+data: 3: 6
+
+event: chunk
+data: 4: 24
+
+event: chunk
+data: 5: 120
+
+event: done
+data:
+```
+
+### Call via HTTP — plain JSON
+
+```bash
+curl -X POST http://localhost:8000/skills/factorial \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d '{"n": 5}'
+```
+
+```json
+{"chunks": ["start: 1", "2: 2", "3: 6", "4: 24", "5: 120"]}
+```
+
+### Connect an MCP client
+
+The MCP server is automatically available at:
+
+```
+http://localhost:8000/mcp
+```
+
+Add it to **Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "harnessapi": {
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+Or add it to **Cursor** settings under MCP servers.
+
+The `factorial` skill is automatically registered as an MCP tool with parameter `input.n: int`.
+
+---
+
+## Skill folder structure
+
+```
+skills/
+└── my_skill/
+    ├── handler.py        # REQUIRED — async def handle(input: Input) -> Output
+    ├── models.py         # REQUIRED — class Input(SkillInput), class Output(SkillOutput)
+    ├── skill.toml        # optional — metadata
+    ├── defaults/
+    │   └── input.json    # optional — default values shown in OpenAPI docs
+    └── examples/
+        └── 01.json       # optional — {input: {...}, output: {...}} example pairs
+```
+
+**`skill.toml`** (all optional):
+```toml
+[skill]
+description  = "What this skill does"
+is_mcp       = true      # expose as MCP tool (default: true)
+tags         = ["math"]
+timeout_secs = 30
+```
+
+### Streaming vs non-streaming
+
+Return a value → non-streaming (single `result` SSE event):
+```python
+async def handle(input: Input) -> Output:
+    return Output(...)
+```
+
+Use `yield` → streaming (multiple `chunk` SSE events):
+```python
+async def handle(input: Input):
+    for item in compute_steps(input):
+        yield item
+```
+
+---
+
+## Decorator API (no folder needed)
+
+```python
+from harnessapi import HarnessAPI, SkillInput, SkillOutput, skill
+
+class TranslateInput(SkillInput):
+    text: str
+    target_lang: str = "es"
+
+class TranslateOutput(SkillOutput):
+    translated: str
+
+@skill(
+    name="translate",
+    input_model=TranslateInput,
+    output_model=TranslateOutput,
+    is_mcp=True,
+)
+async def translate_handler(input: TranslateInput) -> TranslateOutput:
+    return TranslateOutput(translated=f"[{input.target_lang}] {input.text}")
+
+app = HarnessAPI(title="My Skills")
+```
+
+---
+
+## Runtime edit endpoint (advanced)
+
+Enable hot-swapping a skill's handler over HTTP:
+
+```python
+app = HarnessAPI(skills_dir="./skills", enable_edit_endpoints=True)
+```
+
+```bash
+curl -X POST http://localhost:8000/skills/factorial/edit \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_code": "async def handle(input):\n    yield f\"custom: {input.n}\"",
+    "persist": false
+  }'
+```
+
+> **Security note**: The edit endpoint executes arbitrary Python. Always protect it with authentication middleware in production. It is disabled by default.
+
+---
+
+## SSE event protocol
+
+| Event    | When                                      |
+|----------|-------------------------------------------|
+| `chunk`  | Each yielded value from a streaming handler |
+| `result` | The final output of a non-streaming handler |
+| `done`   | Always the last event                     |
+| `error`  | Handler raised an exception               |
+
+---
+
+## OpenAPI docs
+
+Interactive docs are available at `http://localhost:8000/docs` — all skills appear as documented POST endpoints with their Pydantic schemas.

harnessapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+harnessapi/__init__.py,sha256=EIZQEF2_rMhczZxn85rk2KTj8eAGkQUrsQLQeZQCkXg,573
+harnessapi/app.py,sha256=v7ynjYn1WVLchW32XRUQVoI36kb-IAQlprJcq5lu0CE,2620
+harnessapi/decorators.py,sha256=lYmOfU5ai3SCvQlwrq7-Y33s1ZO7ecy5fyducMxs1pg,2163
+harnessapi/discovery.py,sha256=oDcb3octkvnVme0_uAgdsGFARrcSyDeVjp7NVuH1VPg,5392
+harnessapi/edit.py,sha256=LCX_9QgdwRHzsaEvpQEXU1E2mlqzAFrL4ZpBNL890xM,1264
+harnessapi/exceptions.py,sha256=Deiimh7ouYRD7lBjW3jpy3hRRD0P8ZjO44MK4yTlA-I,645
+harnessapi/mcp.py,sha256=8xQ1kFiJoTp2capJ7FRUzxZOcm6AAaXsCYhM8lI-QmU,1859
+harnessapi/models.py,sha256=NVwYVMIBpaWyZaISxAHzq7iOw0oDbrg8217iLdTuPh4,198
+harnessapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+harnessapi/routing.py,sha256=6H4gjJh9XhK2oR0OR2DQ0PGg-L6kz6njtWP28NmynHk,3078
+harnessapi/skill.py,sha256=9k5UuNqn6CpLacywUTIBjsmkfzkbVi8ytcyEqUXKBrY,968
+harnessapi/streaming.py,sha256=gKVTfIhTotWkRCEY6MgdH2LKFDqC-zHl7fUpHhnWa6Y,1540
+harnessapi-0.1.0.dist-info/METADATA,sha256=T6J-01cyXJwQggI_s26ah4QwvRgl40EEqFkixh_Pb3M,6455
+harnessapi-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+harnessapi-0.1.0.dist-info/licenses/LICENSE,sha256=0H9MlwWVGJvUdyMbKwuA1ptbwh11sC8Mq1WirKsyZhQ,1067
+harnessapi-0.1.0.dist-info/RECORD,,

harnessapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

harnessapi-0.1.0.dist-info/licenses/LICENSE

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