toolfuncs 1.0.0__tar.gz → 1.2.0__tar.gz

{toolfuncs-1.0.0 → toolfuncs-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolfuncs
-Version: 1.0.0
+Version: 1.2.0
 Summary: Typed Python functions with native Python, CLI, and MCP interfaces
 Project-URL: Repository, https://github.com/nimashoghi/toolfuncs
 Project-URL: Issues, https://github.com/nimashoghi/toolfuncs/issues
@@ -185,24 +185,55 @@ Function commands inherit help and error presentation from their parent app. All
 
 ## Use MCP
 
-Register each script or opted-in package executable explicitly in your MCP client. For example, a client using an `mcpServers` configuration can launch:
+Register one server to expose the effective PATH catalog. Scripts and opted-in package executables remain separate tool families:
 
 ```json
 {
   "mcpServers": {
-    "weather": {
+    "toolfuncs": {
       "command": "/absolute/path/to/toolfuncs",
-      "args": ["mcp", "/absolute/path/to/weather-report"]
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-`toolfuncs mcp SOURCE` prepares the same isolated dependency environment as the CLI and starts one stdio server. Use `--prepared` only when the selected interpreter already contains the source's dependencies. Toolfuncs does not edit client configuration. Each server exposes all registered operations; restart it after source or dependency changes.
+`toolfuncs mcp` captures PATH and starts one persistent child per family, using each source's isolated dependency environment. Children inherit the launch directory and environment. Startup is bounded to 120 seconds, including dependency preparation, with at most eight families starting concurrently. Configure the client's startup timeout to at least 180 seconds for cold installations. Failed families appear in `catalog` with an error; healthy families remain callable. `toolfuncs doctor` loads all families and exits nonzero if any are unavailable. It does not invoke their operations. Use `toolfuncs doctor SOURCE` for the full source documentation and help checks.
+
+The server's operation catalog remains fixed until restart. A crashed child becomes unavailable and is not restarted automatically. Interrupted operations are never replayed, since their side effects may already have occurred. Ordinary function exceptions remain tool errors and leave the family available. Shutdown closes the children. Installing tools, changing PATH, or updating source/dependencies requires restarting the server.
+
+`toolfuncs mcp SOURCE` remains available to serve one source or opted-in package command. Use `--prepared` only when the selected interpreter already contains every selected source's dependencies. Toolfuncs does not edit client configuration.
+
+### Progressive discovery
+
+The hook advertises families. Inspect one group at a time, then one selected operation:
+
+```console
+toolfuncs catalog
+toolfuncs commands weather-report
+toolfuncs commands weather-report --group '["records"]'
+toolfuncs inspect-operation weather-report '["records", "show"]'
+```
+
+The generic MCP server exposes these same three discovery functions as `catalog`, `commands`, and `inspect_operation`. Group views contain only immediate child names and short descriptions. Selected operation views contain the original input/output schemas, documentation, canonical CLI argv, MCP name, and a Python attribute when it is verifiably exported by the source module. Do not reconstruct Python access from an MCP name: registered aliases and nested CLI groups need not match Python attributes.
+
+Python uses the same bound functions:
+
+```python
+from toolfuncs.sdk import ToolCatalog
+
+async with ToolCatalog() as catalog:
+    families = catalog.catalog()  # static discovery, no child startup
+    await catalog.start(["weather-report"])
+    children = catalog.commands("weather-report")
+    detail = catalog.inspect_operation("weather-report", ["records", "show"])
+```
+
+In Codex Code Mode, use toolfuncs discovery to select an operation, resolve its runtime name from `ALL_TOOLS`, and invoke `tools[name](arguments)`. Retain deferred MCP exposure; native tool search is unnecessary. In Claude Code, keep the server's tools deferred (`"alwaysLoad": false` on supported versions), load the selected tool with `ToolSearch` query `select:mcp__toolfuncs__NAME`, then call it normally. Claude still exposes operation names initially. These context policies belong to the client; generic MCP clients may expose all schemas. For the agent hook's client-specific guidance, set `TOOLFUNCS_MCP_SERVER=toolfuncs` in the host environment when that server is registered.
 
 For programmatic use, `server = app.to_mcp()` returns a FastMCP server. Sync functions use FastMCP's thread dispatch and async functions are awaited. FastMCP owns request handling and cancellation. MCP calls do not share live state with an IPython kernel. The function implementation is shared.
 
-A nested CLI command such as `records show` becomes `records__show`; hyphens become underscores. Aliases remain CLI aliases. Ambiguous or invalid MCP names fail at startup. Every successful MCP result has structured content `{"result": value}`, including scalar and null results, plus JSON text content. Exceptions become MCP tool errors.
+A nested CLI command such as `records show` becomes `records__show`; the PATH server prefixes the family, for example `weather_report__records__show`. Hyphens become underscores. Aliases remain CLI aliases. Collisions and names exceeding 64 characters fail explicitly. Every successful MCP result has structured content `{"result": value}`, including scalar and null results, plus JSON text content. Exceptions become MCP tool errors.
 
 Use stderr for logs and diagnostics. Stdout belongs to the CLI result or MCP protocol; an operation that prints to stdout can corrupt that stream. Durable background tasks, push notifications, remote hosting, resources and prompts are outside the 1.0 interface.
 
@@ -234,7 +265,7 @@ Declare `toolfuncs>=1,<2` in PEP 723 dependencies to make the required major ver
 
 The description, either `[tool.toolfuncs].description` or a package module's first docstring line, is the line agents read in `toolfuncs list` and session-start catalogs when they choose a tool. Write one sentence that says what the tool does for its caller. Keep implementation details, compatibility notes and contract caveats out of it; put them in later docstring text or in command docstrings.
 
-Descriptions are static by default. A tool whose available domain surface changes at runtime may opt into a last-known catalog description with `dynamic = true`:
+Descriptions are static by default. A script whose available domain surface changes at runtime may opt into a last-known catalog description with `dynamic = true`:
 
 ```toml
 [tool.toolfuncs]
@@ -262,6 +293,15 @@ Only functions registered on `app` become CLI commands. Imported functions and `
 
 No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its declared Python name before invoking its module-level app. Consequently, `weather-report ...` is the supported CLI while `python weather-report ...` merely defines the module and exits, or fails if its dependencies are not already installed.
 
+Packaged tools opt in with an additional matching entry point:
+
+```toml
+[project.entry-points."toolfuncs.dynamic_description"]
+my-tool = "my_package.tools:app"
+```
+
+Keep the matching `project.scripts` and `project.entry-points.toolfuncs` declarations. Publish descriptions through the same `toolsdk.publish_description` API. Discovery reads the current user's published line on each call and falls back to the module docstring when no valid line exists; it does not import the tool or access its service.
+
 ## Package-backed implementations
 
 A toolfunc remains one script even when most of its implementation lives in a package:
@@ -332,9 +372,12 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 
 ```console
 toolfuncs SOURCE [ARGS...]
-toolfuncs doctor SOURCE
-toolfuncs mcp [--prepared] SOURCE
+toolfuncs doctor [--prepared] [SOURCE]
+toolfuncs mcp [--prepared] [SOURCE]
 toolfuncs list
+toolfuncs catalog
+toolfuncs commands FAMILY [--group JSON_PATH]
+toolfuncs inspect-operation FAMILY JSON_PATH
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
 

{toolfuncs-1.0.0 → toolfuncs-1.2.0}/README.md

@@ -167,24 +167,55 @@ Function commands inherit help and error presentation from their parent app. All
 
 ## Use MCP
 
-Register each script or opted-in package executable explicitly in your MCP client. For example, a client using an `mcpServers` configuration can launch:
+Register one server to expose the effective PATH catalog. Scripts and opted-in package executables remain separate tool families:
 
 ```json
 {
   "mcpServers": {
-    "weather": {
+    "toolfuncs": {
       "command": "/absolute/path/to/toolfuncs",
-      "args": ["mcp", "/absolute/path/to/weather-report"]
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-`toolfuncs mcp SOURCE` prepares the same isolated dependency environment as the CLI and starts one stdio server. Use `--prepared` only when the selected interpreter already contains the source's dependencies. Toolfuncs does not edit client configuration. Each server exposes all registered operations; restart it after source or dependency changes.
+`toolfuncs mcp` captures PATH and starts one persistent child per family, using each source's isolated dependency environment. Children inherit the launch directory and environment. Startup is bounded to 120 seconds, including dependency preparation, with at most eight families starting concurrently. Configure the client's startup timeout to at least 180 seconds for cold installations. Failed families appear in `catalog` with an error; healthy families remain callable. `toolfuncs doctor` loads all families and exits nonzero if any are unavailable. It does not invoke their operations. Use `toolfuncs doctor SOURCE` for the full source documentation and help checks.
+
+The server's operation catalog remains fixed until restart. A crashed child becomes unavailable and is not restarted automatically. Interrupted operations are never replayed, since their side effects may already have occurred. Ordinary function exceptions remain tool errors and leave the family available. Shutdown closes the children. Installing tools, changing PATH, or updating source/dependencies requires restarting the server.
+
+`toolfuncs mcp SOURCE` remains available to serve one source or opted-in package command. Use `--prepared` only when the selected interpreter already contains every selected source's dependencies. Toolfuncs does not edit client configuration.
+
+### Progressive discovery
+
+The hook advertises families. Inspect one group at a time, then one selected operation:
+
+```console
+toolfuncs catalog
+toolfuncs commands weather-report
+toolfuncs commands weather-report --group '["records"]'
+toolfuncs inspect-operation weather-report '["records", "show"]'
+```
+
+The generic MCP server exposes these same three discovery functions as `catalog`, `commands`, and `inspect_operation`. Group views contain only immediate child names and short descriptions. Selected operation views contain the original input/output schemas, documentation, canonical CLI argv, MCP name, and a Python attribute when it is verifiably exported by the source module. Do not reconstruct Python access from an MCP name: registered aliases and nested CLI groups need not match Python attributes.
+
+Python uses the same bound functions:
+
+```python
+from toolfuncs.sdk import ToolCatalog
+
+async with ToolCatalog() as catalog:
+    families = catalog.catalog()  # static discovery, no child startup
+    await catalog.start(["weather-report"])
+    children = catalog.commands("weather-report")
+    detail = catalog.inspect_operation("weather-report", ["records", "show"])
+```
+
+In Codex Code Mode, use toolfuncs discovery to select an operation, resolve its runtime name from `ALL_TOOLS`, and invoke `tools[name](arguments)`. Retain deferred MCP exposure; native tool search is unnecessary. In Claude Code, keep the server's tools deferred (`"alwaysLoad": false` on supported versions), load the selected tool with `ToolSearch` query `select:mcp__toolfuncs__NAME`, then call it normally. Claude still exposes operation names initially. These context policies belong to the client; generic MCP clients may expose all schemas. For the agent hook's client-specific guidance, set `TOOLFUNCS_MCP_SERVER=toolfuncs` in the host environment when that server is registered.
 
 For programmatic use, `server = app.to_mcp()` returns a FastMCP server. Sync functions use FastMCP's thread dispatch and async functions are awaited. FastMCP owns request handling and cancellation. MCP calls do not share live state with an IPython kernel. The function implementation is shared.
 
-A nested CLI command such as `records show` becomes `records__show`; hyphens become underscores. Aliases remain CLI aliases. Ambiguous or invalid MCP names fail at startup. Every successful MCP result has structured content `{"result": value}`, including scalar and null results, plus JSON text content. Exceptions become MCP tool errors.
+A nested CLI command such as `records show` becomes `records__show`; the PATH server prefixes the family, for example `weather_report__records__show`. Hyphens become underscores. Aliases remain CLI aliases. Collisions and names exceeding 64 characters fail explicitly. Every successful MCP result has structured content `{"result": value}`, including scalar and null results, plus JSON text content. Exceptions become MCP tool errors.
 
 Use stderr for logs and diagnostics. Stdout belongs to the CLI result or MCP protocol; an operation that prints to stdout can corrupt that stream. Durable background tasks, push notifications, remote hosting, resources and prompts are outside the 1.0 interface.
 
@@ -216,7 +247,7 @@ Declare `toolfuncs>=1,<2` in PEP 723 dependencies to make the required major ver
 
 The description, either `[tool.toolfuncs].description` or a package module's first docstring line, is the line agents read in `toolfuncs list` and session-start catalogs when they choose a tool. Write one sentence that says what the tool does for its caller. Keep implementation details, compatibility notes and contract caveats out of it; put them in later docstring text or in command docstrings.
 
-Descriptions are static by default. A tool whose available domain surface changes at runtime may opt into a last-known catalog description with `dynamic = true`:
+Descriptions are static by default. A script whose available domain surface changes at runtime may opt into a last-known catalog description with `dynamic = true`:
 
 ```toml
 [tool.toolfuncs]
@@ -244,6 +275,15 @@ Only functions registered on `app` become CLI commands. Imported functions and `
 
 No `if __name__ == "__main__":` block is required. The operating system passes the source path to the shebang interpreter, and toolfuncs imports the source under its declared Python name before invoking its module-level app. Consequently, `weather-report ...` is the supported CLI while `python weather-report ...` merely defines the module and exits, or fails if its dependencies are not already installed.
 
+Packaged tools opt in with an additional matching entry point:
+
+```toml
+[project.entry-points."toolfuncs.dynamic_description"]
+my-tool = "my_package.tools:app"
+```
+
+Keep the matching `project.scripts` and `project.entry-points.toolfuncs` declarations. Publish descriptions through the same `toolsdk.publish_description` API. Discovery reads the current user's published line on each call and falls back to the module docstring when no valid line exists; it does not import the tool or access its service.
+
 ## Package-backed implementations
 
 A toolfunc remains one script even when most of its implementation lives in a package:
@@ -314,9 +354,12 @@ Setup does not discover, copy, register, link, synchronize, or remove tools. The
 
 ```console
 toolfuncs SOURCE [ARGS...]
-toolfuncs doctor SOURCE
-toolfuncs mcp [--prepared] SOURCE
+toolfuncs doctor [--prepared] [SOURCE]
+toolfuncs mcp [--prepared] [SOURCE]
 toolfuncs list
+toolfuncs catalog
+toolfuncs commands FAMILY [--group JSON_PATH]
+toolfuncs inspect-operation FAMILY JSON_PATH
 toolfuncs setup [--bin-dir DIRECTORY]
 ```
 

{toolfuncs-1.0.0 → toolfuncs-1.2.0}/docs/contract.md

@@ -8,6 +8,8 @@ Toolfuncs projects one explicitly registered set of typed Python functions into
 
 An installed distribution opts a console script into discovery by declaring the same command name and `module:app` value in its `console_scripts` and `toolfuncs` entry-point groups. Authors normally express these as `[project.scripts]` and `[project.entry-points.toolfuncs]` in `pyproject.toml`. The module contains the same module-level `app` and decorated typed functions used by script tools. There is no hand-maintained launcher: normal installers generate it.
 
+A packaged tool may also declare that same name and value in the `toolfuncs.dynamic_description` entry-point group (`[project.entry-points."toolfuncs.dynamic_description"]`). Discovery then uses its valid published one-line description, with the module docstring as fallback, just as a script with `dynamic = true` does. The dynamic entry must match both ordinary declarations; it does not register an additional command. Discovery remains local and never imports the module. Published state is scoped to the current user's state directory and CLI identity, not to a package generation.
+
 The public executable's kebab-case name determines its snake-case facade name, with the same reserved-name checks and PATH precedence as scripts. uv-launch's versioned installation records locate the actual executable and its metadata roots, capturing a single retained generation. The actual executable must have one distribution owner across all RECORD files, a matching strong checksum, and paired console-script and toolfuncs entry points. Discovery trusts the installer to implement those entry points. It does not parse generated Python or shell bodies or authenticate package metadata. Discovery statically reads the installed module's first docstring line and requires inspectable Python source.
 
 Metadata in the current interpreter is also supported, including additive native dependency preparation. Unmanaged foreign environments are not inferred from launcher text; install those commands through uv-launch. Discovery never imports target packages, starts a subprocess, installs dependencies, or queries the network. `toolfuncs.sdk.discover(path=None)` returns the same `Catalog` as CLI listing, with `tools` and `invalid_tools`.
@@ -53,7 +55,11 @@ Cyclopts tokenizes and binds CLI arguments. Its central converter uses Pydantic'
 
 ## MCP interface
 
-`toolfuncs mcp SOURCE` prepares dependencies and serves one source or opted-in package executable over stdio. `--prepared` uses the current interpreter without dependency preparation. Each script is registered separately in the client's configuration. `app.to_mcp(name=...)` produces a FastMCP server for programmatic use.
+`toolfuncs mcp SOURCE` prepares dependencies and serves one source or opted-in package executable over stdio. Omitting SOURCE serves the effective PATH catalog with one isolated persistent child per family. `--prepared` uses the current interpreter without dependency preparation. `app.to_mcp(name=...)` produces a FastMCP server for programmatic use.
+
+The PATH server snapshots discovery and operation schemas at startup, retains healthy families when another fails, and records failed families in its `catalog` discovery result. Each native tool name is prefixed by its family Python name and `__`; the complete name must be unique and at most 64 characters. There is no automatic refresh, reconnect or failed-call replay. Child processes inherit the server's launch directory and environment. They are closed when the server exits.
+
+`catalog`, `commands`, and `inspect_operation` use the same implementations in MCP, the management CLI and `toolfuncs.sdk.ToolCatalog`. Each group listing exposes immediate children only. One selected operation exposes its authoritative contract. The Python catalog is an async context manager; `await catalog.start()` loads all families, or a supplied sequence selects families. Static `sdk.discover()` and `toolfuncs list` remain import-free. Native domain calls still use the original functions through `toolfuncs.NAME`; discovery does not turn Python domain calls into RPC.
 
 Canonical command paths become tool names by replacing hyphens with underscores and joining path segments with `__`. A root default operation uses its function name. Names must contain 1-64 ASCII letters, digits, underscores or hyphens. CLI aliases are deduplicated; name collisions fail.
 
@@ -116,7 +122,7 @@ Successful default CLI operations render one Python value through Rich on an int
 
 Setup does not discover, install, copy, link, register, synchronize, or remove tool sources. Adding and removing tools are ordinary filesystem operations in directories already on `PATH`.
 
-The public management commands are `toolfuncs mcp [--prepared] SOURCE`, `toolfuncs doctor SOURCE`, `toolfuncs list`, and `toolfuncs setup [--bin-dir DIRECTORY]`. The explicit-source execution form is `toolfuncs SOURCE [ARGS...]`; it is not a universal name dispatcher. Tools on `PATH` are invoked directly by their own CLI names. There is no `run`, `exec`, `describe`, or `sync` command.
+The public management commands include `toolfuncs mcp [--prepared] [SOURCE]`, `toolfuncs doctor [--prepared] [SOURCE]`, `toolfuncs list`, `toolfuncs catalog`, `toolfuncs commands FAMILY [--group JSON_PATH]`, `toolfuncs inspect-operation FAMILY JSON_PATH`, and `toolfuncs setup [--bin-dir DIRECTORY]`. Doctor without SOURCE checks aggregate loading and name validity; doctor with SOURCE also checks its authoring documentation and generated help. The explicit-source execution form is `toolfuncs SOURCE [ARGS...]`; it is not a universal name dispatcher. Tools on `PATH` are invoked directly by their own CLI names. There is no generic operation-call command.
 
 ## Compatibility
 

{toolfuncs-1.0.0 → toolfuncs-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "toolfuncs"
-version = "1.0.0"
+version = "1.2.0"
 description = "Typed Python functions with native Python, CLI, and MCP interfaces"
 readme = "README.md"
 authors = [

{toolfuncs-1.0.0 → toolfuncs-1.2.0}/src/toolfuncs/__main__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import sys
 from collections.abc import Iterator, Sequence
@@ -31,9 +32,12 @@ Usage:
   toolfuncs --version
   toolfuncs SOURCE [ARGS...]
   toolfuncs run-prepared SOURCE [ARGS...]
-  toolfuncs doctor [--prepared] SOURCE
-  toolfuncs mcp [--prepared] SOURCE
+  toolfuncs doctor [--prepared] [SOURCE]
+  toolfuncs mcp [--prepared] [SOURCE]
   toolfuncs list
+  toolfuncs catalog
+  toolfuncs commands FAMILY [--group JSON_PATH]
+  toolfuncs inspect-operation FAMILY JSON_PATH
   toolfuncs setup [--bin-dir DIRECTORY]
 
 A toolfunc is an executable Python script whose first line is exactly:
@@ -53,8 +57,12 @@ run-prepared and doctor --prepared use the current interpreter without resolving
 or installing dependencies. Installers must prepare the script's declared runtime
 first. They still validate the source and its Python-version requirement.
 
-mcp serves one selected script or installed package command over stdio. Register
-this command explicitly with your MCP client. No PATH aggregation or live reload.
+mcp serves native tools from PATH over stdio, or one selected SOURCE. Register it
+once with your client. Each family runs in its own persistent process. Restart
+the server after installing or changing tools; there is no automatic reload.
+Discovery proceeds from catalog to commands to inspect-operation. These commands
+share their implementation with the Python ToolCatalog and native MCP discovery.
+doctor without SOURCE checks all discovered families and reports partial failures.
 """
 
 
@@ -108,11 +116,27 @@ def main(argv: Sequence[str] | None = None) -> int:
         _print_json(_catalog_payload(catalog))
         _warn_invalid_tools(catalog.invalid_tools)
         return 0
+    if command in {"catalog", "commands", "inspect-operation"}:
+        from ._catalog import run_discovery
+
+        return asyncio.run(run_discovery(command, tokens))
     if command in {"doctor", "__doctor-source"}:
         prepared = command == "__doctor-source"
         if command == "doctor" and tokens[:1] == ["--prepared"]:
             prepared = True
             tokens.pop(0)
+        if not tokens and command == "doctor":
+            from ._catalog import doctor_catalog
+
+            families = asyncio.run(doctor_catalog(prepared=prepared))
+            healthy = all(family.status == "ready" for family in families)
+            _print_json(
+                {
+                    "status": "success" if healthy else "error",
+                    "families": [family.model_dump(mode="json") for family in families],
+                }
+            )
+            return 0 if healthy else 1
         if len(tokens) != 1:
             raise SystemExit("usage: toolfuncs doctor SOURCE")
         if not prepared and Path(tokens[0]).is_file():
@@ -136,6 +160,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         if tokens[:1] == ["--prepared"]:
             prepared = True
             tokens.pop(0)
+        if not tokens and command == "mcp":
+            from ._catalog import create_path_server
+
+            create_path_server(prepared=prepared).run(transport="stdio", show_banner=False)
+            return 0
         if len(tokens) != 1:
             raise SystemExit("usage: toolfuncs mcp [--prepared] SOURCE")
         source = Path(tokens[0])
@@ -144,7 +173,10 @@ def main(argv: Sequence[str] | None = None) -> int:
             raise AssertionError("exec returned")
         # Import diagnostics must not be mistaken for JSON-RPC protocol frames.
         with redirect_stdout(sys.stderr), _tool_program_name(source):
-            server = _application(_load_prepared_source(source)).to_mcp(name=source.name)
+            from ._mcp import create_server
+
+            module = _load_prepared_source(source)
+            server = create_server(_application(module), name=source.name, source_module=module)
         server.run(transport="stdio", show_banner=False)
         return 0
     if command == "setup":