functualize-mcp 0.1.0__tar.gz

functualize_mcp-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: functualize-mcp
+Version: 0.1.0
+Summary: MCP delivery adapter plugin for functualize — exposes jobs as MCP tools via FastMCP
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: functualize<1.0.0,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.82.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-mcp
+
+> **Status: Published** — Independently installable from PyPI.
+
+MCP delivery adapter plugin for functualize — exposes jobs as MCP tools via FastMCP. External AI agents (Goose, Claude, Cursor) can discover and invoke functualize jobs through the standardized [Model Context Protocol](https://modelcontextprotocol.io/) interface without any manual wiring.
+
+## Installation
+
+```bash
+pip install functualize-mcp
+```
+
+## Quick Start
+
+```python
+from functualize_mcp import JobToolTranslator, MCPToolDef, SchemaExporter
+
+# Translate a job descriptor into an MCP tool definition
+translator = JobToolTranslator()
+tool_def = translator.translate(my_job_descriptor)
+print(tool_def.name, tool_def.description)
+
+# Export all job schemas as OpenAI function calling JSON
+exporter = SchemaExporter(translator)
+openai_json = exporter.export_openai(descriptors)
+```
+
+## Features
+
+- Automatic job-to-tool translation with JSON Schema input generation from config models
+- Dual transport support: stdio (default) and HTTP+SSE for networked agents
+- Job visibility filtering via include/exclude tags and job name exclusion lists
+- Multi-format schema export: JSON (MCP), Markdown, OpenAI function calling, TypeScript
+- Multi-server management: start, list, and stop background HTTP servers
+- Workflow inspection and advancement tools for paused workflow steps
+- Async job execution with polling via `run_job_async` / `get_execution_status`
+- AI outbound gate strategy for workflow checkpoint serialization
+
+## API Reference
+
+Public classes and functions exported by this plugin:
+
+- `MCPAdapterPlugin` — Plugin entry point implementing the AdapterPlugin protocol; registers MCP tools at boot
+- `MCPConfig` — Pydantic configuration model controlling transport, port, host, tag filters, and management features
+- `MCPServer` — FastMCP wrapper that discovers jobs, registers tools, and serves via stdio or HTTP+SSE
+- `JobToolTranslator` — Translates JobDescriptors into MCPToolDef instances using docstrings and config schemas
+- `MCPToolDef` — Frozen dataclass representing an MCP tool (name, description, input_schema, annotations)
+- `SchemaExporter` — Exports job schemas in JSON, Markdown, OpenAI, and TypeScript formats
+- `MCPToolRegistry` — Registers core MCP tools (discover_jobs, get_job_schema, run_job, run_job_async, get_execution_status)
+- `MCPHistoryToolRegistry` — Registers execution history inspection tools
+- `MCPManagementToolRegistry` — Registers multi-server management meta-tools
+- `MCPTaskToolRegistry` — Registers task-domain MCP tools
+- `WorkflowToolProvider` — Registers workflow state inspection and resume tools
+- `ServerManager` — Manages background MCP HTTP server processes (start, list, stop)
+- `ServerInfo` — Dataclass describing a managed server (name, directory, port, pid, status)
+- `AIOutboundGateResolver` — Gate strategy resolver for AI outbound workflow checkpoints
+- `register_ai_outbound_gate_strategy()` — Registers the ai_outbound gate strategy and preset with an app
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-mcp/tests/ -v
+```

functualize_mcp-0.1.0/README.md

@@ -0,0 +1,65 @@
+# functualize-mcp
+
+> **Status: Published** — Independently installable from PyPI.
+
+MCP delivery adapter plugin for functualize — exposes jobs as MCP tools via FastMCP. External AI agents (Goose, Claude, Cursor) can discover and invoke functualize jobs through the standardized [Model Context Protocol](https://modelcontextprotocol.io/) interface without any manual wiring.
+
+## Installation
+
+```bash
+pip install functualize-mcp
+```
+
+## Quick Start
+
+```python
+from functualize_mcp import JobToolTranslator, MCPToolDef, SchemaExporter
+
+# Translate a job descriptor into an MCP tool definition
+translator = JobToolTranslator()
+tool_def = translator.translate(my_job_descriptor)
+print(tool_def.name, tool_def.description)
+
+# Export all job schemas as OpenAI function calling JSON
+exporter = SchemaExporter(translator)
+openai_json = exporter.export_openai(descriptors)
+```
+
+## Features
+
+- Automatic job-to-tool translation with JSON Schema input generation from config models
+- Dual transport support: stdio (default) and HTTP+SSE for networked agents
+- Job visibility filtering via include/exclude tags and job name exclusion lists
+- Multi-format schema export: JSON (MCP), Markdown, OpenAI function calling, TypeScript
+- Multi-server management: start, list, and stop background HTTP servers
+- Workflow inspection and advancement tools for paused workflow steps
+- Async job execution with polling via `run_job_async` / `get_execution_status`
+- AI outbound gate strategy for workflow checkpoint serialization
+
+## API Reference
+
+Public classes and functions exported by this plugin:
+
+- `MCPAdapterPlugin` — Plugin entry point implementing the AdapterPlugin protocol; registers MCP tools at boot
+- `MCPConfig` — Pydantic configuration model controlling transport, port, host, tag filters, and management features
+- `MCPServer` — FastMCP wrapper that discovers jobs, registers tools, and serves via stdio or HTTP+SSE
+- `JobToolTranslator` — Translates JobDescriptors into MCPToolDef instances using docstrings and config schemas
+- `MCPToolDef` — Frozen dataclass representing an MCP tool (name, description, input_schema, annotations)
+- `SchemaExporter` — Exports job schemas in JSON, Markdown, OpenAI, and TypeScript formats
+- `MCPToolRegistry` — Registers core MCP tools (discover_jobs, get_job_schema, run_job, run_job_async, get_execution_status)
+- `MCPHistoryToolRegistry` — Registers execution history inspection tools
+- `MCPManagementToolRegistry` — Registers multi-server management meta-tools
+- `MCPTaskToolRegistry` — Registers task-domain MCP tools
+- `WorkflowToolProvider` — Registers workflow state inspection and resume tools
+- `ServerManager` — Manages background MCP HTTP server processes (start, list, stop)
+- `ServerInfo` — Dataclass describing a managed server (name, directory, port, pid, status)
+- `AIOutboundGateResolver` — Gate strategy resolver for AI outbound workflow checkpoints
+- `register_ai_outbound_gate_strategy()` — Registers the ai_outbound gate strategy and preset with an app
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-mcp/tests/ -v
+```

functualize_mcp-0.1.0/examples/README.md

@@ -0,0 +1,52 @@
+# functualize-mcp Examples
+
+The full MCP reference example: exposing jobs as MCP tools that AI agents (Claude, Cursor, Goose) can discover and call. For the minimal narrative version, see [`examples/quickstart/step6_mcp/`](../../../examples/quickstart/step6_mcp/).
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`weather_tools/`](weather_tools/) | Visibility control, rich `@job_metadata`, and the served tool surface |
+
+## Serving
+
+```bash
+cd plugins/functualize-mcp/examples/weather_tools
+func mcp serve                 # stdio transport (default)
+```
+
+Wire into Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "func",
+      "args": ["mcp", "serve"],
+      "cwd": "/path/to/weather_tools"
+    }
+  }
+}
+```
+
+## The tool surface agents see
+
+Beyond one tool per `visibility="external"` job, the server exposes framework tools:
+
+| Tool | Purpose |
+|------|---------|
+| `discover_jobs` | List external jobs with descriptions and tags |
+| `get_job_schema` | Full input schema (from the job's Pydantic config) |
+| `run_job` / `run_job_async` | Execute synchronously or in the background |
+| `get_execution_status` | Poll an async execution |
+| `get_workflow_state` / `resume_workflow` | Drive gated workflows across turns |
+
+Inspect what would be served without starting the server:
+
+```bash
+func mcp tools
+```
+
+## Tests
+
+```bash
+uv run pytest plugins/functualize-mcp/examples/ -v
+```

functualize_mcp-0.1.0/examples/weather_tools/jobs.py

@@ -0,0 +1,62 @@
+"""Jobs exposed as MCP tools — visibility and metadata reference.
+
+Serve with:
+    func mcp serve
+
+`forecast` and `travel_advice` become MCP tools; `purge_cache` stays
+hidden (visibility="internal"); `refresh` has no metadata and defaults
+to hidden as well.
+"""
+
+from pydantic import BaseModel, Field
+
+from functualize.job import RunContext
+from functualize.job.decorators import job
+
+
+class ForecastConfig(BaseModel):
+    """Configuration for weather jobs — becomes the MCP tool's input schema."""
+
+    city: str = Field(description="City to check")
+    days: int = Field(default=3, ge=1, le=7, description="Days to forecast")
+
+
+@job(
+    extra_description="Get a weather forecast for a city",
+    category="weather",
+    examples=["forecast --city Tokyo --days 5"],
+    tags=["weather", "safe", "read-only"],
+    visibility="external",
+)
+def forecast(config: ForecastConfig, rc: RunContext) -> str:
+    """Fetch the weather forecast for the configured city."""
+    rc.log(f"Fetching {config.days}-day forecast for {config.city}...")
+    return f"{config.city}: 24°C, sunny for the next {config.days} days"
+
+
+@job(
+    extra_description="Advise whether the weather suits outdoor travel plans",
+    category="weather",
+    tags=["weather", "advice"],
+    visibility="external",
+)
+def travel_advice(config: ForecastConfig, rc: RunContext) -> str:
+    """Turn the forecast into a go/no-go travel recommendation."""
+    rc.log(f"Evaluating travel conditions for {config.city}...")
+    return f"{config.city} looks great for outdoor plans this week"
+
+
+@job(
+    extra_description="Purge the local forecast cache",
+    visibility="internal",
+)
+def purge_cache(rc: RunContext) -> str:
+    """Internal maintenance — hidden from MCP agents."""
+    rc.log("Purging forecast cache...")
+    return "cache purged"
+
+
+def refresh(rc: RunContext) -> str:
+    """No metadata at all — also not exposed as an MCP tool."""
+    rc.log("Refreshing data sources...")
+    return "refreshed"

functualize_mcp-0.1.0/examples/weather_tools/test_weather_tools.py

@@ -0,0 +1,31 @@
+"""Tests for the weather_tools MCP example: the visibility contract."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from jobs import ForecastConfig, forecast, purge_cache, refresh, travel_advice
+
+
+def test_external_jobs_carry_full_metadata():
+    for job in (forecast, travel_advice):
+        decl = job.__functualize_job__
+        assert decl.visibility == "external"
+        assert decl.extra_description
+        assert "weather" in decl.tags
+
+
+def test_internal_job_is_marked_hidden():
+    assert purge_cache.__functualize_job__.visibility == "internal"
+
+
+def test_unannotated_job_has_no_declaration():
+    assert not hasattr(refresh, "__functualize_job__")
+
+
+def test_jobs_run_directly():
+    rc = MagicMock()
+    assert "Tokyo" in forecast(ForecastConfig(city="Tokyo"), rc)
+    assert "Tokyo" in travel_advice(ForecastConfig(city="Tokyo"), rc)

functualize_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "functualize-mcp"
+version = "0.1.0"
+description = "MCP delivery adapter plugin for functualize — exposes jobs as MCP tools via FastMCP"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "functualize>=0.1.0,<1.0.0",
+    "fastmcp>=0.1.0",
+]
+
+[project.entry-points."functualize.plugins"]
+mcp = "functualize_mcp:MCPAdapterPlugin"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "hypothesis>=6.82.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+functualize = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_mcp"]

functualize_mcp-0.1.0/src/functualize_mcp/__init__.py

@@ -0,0 +1,86 @@
+"""Functualize MCP Plugin — exposes jobs as MCP tools via FastMCP.
+
+Provides an MCP delivery adapter that translates functualize jobs into
+MCP tools, allowing external AI agents (Goose, Claude, Cursor) to discover
+and invoke jobs through the Model Context Protocol.
+"""
+
+from functualize_mcp._plugin import MCPAdapterPlugin
+
+__all__ = [
+    "AI_OUTBOUND_PRESET_NAME",
+    "AI_OUTBOUND_PRESET_STRATEGIES",
+    "AI_OUTBOUND_STRATEGY_NAME",
+    "AIOutboundGateResolver",
+    "MCPAdapterPlugin",
+    "MCPConfig",
+    "MCPHistoryToolRegistry",
+    "MCPManagementToolRegistry",
+    "MCPServer",
+    "MCPTaskToolRegistry",
+    "MCPToolRegistry",
+    "JobToolTranslator",
+    "MCPToolDef",
+    "SchemaExporter",
+    "ServerInfo",
+    "ServerManager",
+    "WorkflowToolProvider",
+    "register_ai_outbound_gate_strategy",
+]
+
+
+# Lazy loading for heavy symbols (PEP 562)
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "MCPConfig": ("functualize_mcp._config", "MCPConfig"),
+    "AI_OUTBOUND_PRESET_NAME": (
+        "functualize_mcp._gate_strategy",
+        "AI_OUTBOUND_PRESET_NAME",
+    ),
+    "AI_OUTBOUND_PRESET_STRATEGIES": (
+        "functualize_mcp._gate_strategy",
+        "AI_OUTBOUND_PRESET_STRATEGIES",
+    ),
+    "AI_OUTBOUND_STRATEGY_NAME": (
+        "functualize_mcp._gate_strategy",
+        "AI_OUTBOUND_STRATEGY_NAME",
+    ),
+    "AIOutboundGateResolver": (
+        "functualize_mcp._gate_strategy",
+        "AIOutboundGateResolver",
+    ),
+    "register_ai_outbound_gate_strategy": (
+        "functualize_mcp._gate_strategy",
+        "register_ai_outbound_gate_strategy",
+    ),
+    "MCPHistoryToolRegistry": (
+        "functualize_mcp._history_tools",
+        "MCPHistoryToolRegistry",
+    ),
+    "MCPManagementToolRegistry": (
+        "functualize_mcp._management_tools",
+        "MCPManagementToolRegistry",
+    ),
+    "SchemaExporter": ("functualize_mcp._schema_export", "SchemaExporter"),
+    "MCPServer": ("functualize_mcp._server", "MCPServer"),
+    "ServerInfo": ("functualize_mcp._server_manager", "ServerInfo"),
+    "ServerManager": ("functualize_mcp._server_manager", "ServerManager"),
+    "MCPTaskToolRegistry": ("functualize_mcp._task_tools", "MCPTaskToolRegistry"),
+    "MCPToolRegistry": ("functualize_mcp._tools", "MCPToolRegistry"),
+    "JobToolTranslator": ("functualize_mcp._translator", "JobToolTranslator"),
+    "MCPToolDef": ("functualize_mcp._translator", "MCPToolDef"),
+    "WorkflowToolProvider": ("functualize_mcp._workflow_tools", "WorkflowToolProvider"),
+}
+
+
+def __getattr__(name: str):
+    """Lazy-load heavy symbols on first access (PEP 562)."""
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        import importlib
+
+        module = importlib.import_module(module_path)
+        value = getattr(module, attr_name)
+        # Cache it on the module for subsequent fast access
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

functualize_mcp-0.1.0/src/functualize_mcp/_config.py

@@ -0,0 +1,39 @@
+"""MCP adapter configuration model.
+
+Defines MCPConfig pydantic model with transport, networking, filtering,
+and management settings for the MCP server.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+__all__ = ["MCPConfig"]
+
+
+class MCPConfig(BaseModel):
+    """Configuration for the MCP delivery adapter.
+
+    Read from the ``[mcp]`` config section. Controls transport mode,
+    network binding, job visibility filtering, and management features.
+
+    Attributes:
+        transport: Server transport mode — "stdio" (default) or "http".
+        port: HTTP port when using HTTP+SSE transport.
+        host: Bind address for HTTP transport.
+        include_tags: Only expose jobs tagged with at least one of these tags.
+            Empty list means no tag filtering (expose all visible jobs).
+        exclude_tags: Hide jobs tagged with any of these tags.
+        exclude_jobs: Hide specific jobs by name from MCP tool listings.
+        enable_management: When True, expose multi-server management meta-tools.
+    """
+
+    transport: Literal["stdio", "http"] = "stdio"
+    port: int = Field(default=8080, ge=1024, le=65535)
+    host: str = "127.0.0.1"
+    include_tags: list[str] = Field(default_factory=list)
+    exclude_tags: list[str] = Field(default_factory=list)
+    exclude_jobs: list[str] = Field(default_factory=list)
+    enable_management: bool = False