cwl2mcp 0.1.0__tar.gz

cwl2mcp-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Copyright {{ copyright_year }} {{ author_name }}
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.dist/
+build/
+dist/
+.coverage
+coverage.xml
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Environments
+.venv/
+
+# MkDocs
+site/
+
+# Editors
+.idea/
+.vscode/
+.DS_Store
+
+.task
+uv.lock

cwl2mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.1.0]
+
+### Added
+
+- Inital released version.
+
+[unreleased]: https://github.com/transpiler-mate/cwl2mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/transpiler-mate/cwl2mcp/releases/tag/v0.1.0

cwl2mcp-0.1.0/LICENSE

@@ -0,0 +1,4 @@
+Pending license selection.
+
+This repository scaffold was created without assuming a final project license.
+Replace this file with the chosen license text before publishing or distributing releases.

cwl2mcp-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: cwl2mcp
+Version: 0.1.0
+Summary: Derive MCP tool definitions from CWL processes
+Project-URL: Homepage, https://github.com/Transpiler-Mate/cwl2mcp
+Project-URL: Documentation, https://Transpiler-Mate.github.io/cwl2mcp/
+Project-URL: Repository, https://github.com/Transpiler-Mate/cwl2mcp
+Project-URL: Issues, https://github.com/Transpiler-Mate/cwl2mcp/issues
+Project-URL: Changelog, https://github.com/Transpiler-Mate/cwl2mcp/blob/main/CHANGELOG.md
+Author-email: Terradue srl <info@terradue.com>, Fabrice Brito <info@terradue.com>, Simone Tripodi <info@terradue.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: MCP,commonwl,cwl,transpiler-mate
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: cwl2ogc==0.22.2
+Requires-Dist: transpiler-mate-api<2,>=1.0.1
+Provides-Extra: cli
+Requires-Dist: transpiler-mate-runtime<2,>=1.0.0; extra == 'cli'
+Provides-Extra: test
+Requires-Dist: click<9,>=8.4.2; extra == 'test'
+Requires-Dist: cwl-loader>=0.27.0; extra == 'test'
+Requires-Dist: jsonschema[format-nongpl]<5,>=4.26; extra == 'test'
+Requires-Dist: pytest-cov<8,>=7.1.0; extra == 'test'
+Requires-Dist: pytest<10,>=9.1.1; extra == 'test'
+Requires-Dist: transpiler-mate-runtime<2,>=1.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cwl2mcp
+
+[![PyPI - Version](https://img.shields.io/pypi/v/cwl2mcp.svg)](https://pypi.org/project/cwl2mcp)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cwl2mcp.svg)](https://pypi.org/project/cwl2mcp)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/transpiler-mate/cwl2mcp/package.yaml?branch=develop&event=push&label=build&logo=githubactions)](https://github.com/transpiler-mate/cwl2mcp/actions/workflows/package.yaml?query=branch%3Adevelop)
+[![Code coverage](https://img.shields.io/codecov/c/github/transpiler-mate/cwl2mcp/develop?logo=codecov)](https://app.codecov.io/gh/transpiler-mate/cwl2mcp/tree/develop)
+
+A Transpiler Mate plugin deriving MCP tool definitions from parsed CWL v1.0–v1.2
+processes. CWL is authoritative for value structure; EOAP `mcp:Tool` supplies
+agent-facing metadata. This package does not execute CWL or run an MCP server.
+
+## Installation and use
+
+```bash
+python -m pip install './cwl2mcp[cli]'
+transpiler-mate cwl2mcp --output tool.json 'workflow.cwl#main'
+transpiler-mate cwl2mcp --output tools.json workflow.cwl
+```
+
+The current runtime requires document-level schema.org application metadata
+(name, description, dateCreated, license, softwareVersion, softwareHelp, publisher
+and author) before invoking plugins. The complete example and graph fixture show
+this metadata. The Python API does not require it.
+
+The runtime resolves imports and selects processes. A `#process` selection writes
+one MCP Tool object. Without a fragment, output is an object mapping the runtime's
+process IDs to tool definitions, including workflows, CommandLineTools and
+ExpressionTools. This mapping is an export container, not an MCP `tools/list`
+response. JSON keys are sorted, output ends with a newline, and parent directories
+are created. Conversion completes before an existing file is overwritten.
+
+```python
+from cwl_utils.parser import load_document_by_uri
+from cwl2mcp.converter import to_mcp_tool
+
+process = load_document_by_uri('file:///absolute/path/workflow.cwl')
+# Select one process first if the loader returned a list.
+tool = to_mcp_tool(process)
+print(tool.model_dump_json(by_alias=True, exclude_none=True, indent=2))
+```
+
+## Documentation
+
+The documentation follows Diátaxis and is published at
+<https://Transpiler-Mate.github.io/cwl2oci/>:
+
+- tutorials for guided learning;
+- how-to guides for specific tasks;
+- reference for the exact plugin and output contracts;
+- explanation for architecture and design context.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Submit issues at
+<https://github.com/Transpiler-Mate/cwl2oci/issues>.
+
+## License
+
+[![Apache License, Version 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)

cwl2mcp-0.1.0/README.md

@@ -0,0 +1,59 @@
+# cwl2mcp
+
+[![PyPI - Version](https://img.shields.io/pypi/v/cwl2mcp.svg)](https://pypi.org/project/cwl2mcp)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cwl2mcp.svg)](https://pypi.org/project/cwl2mcp)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/transpiler-mate/cwl2mcp/package.yaml?branch=develop&event=push&label=build&logo=githubactions)](https://github.com/transpiler-mate/cwl2mcp/actions/workflows/package.yaml?query=branch%3Adevelop)
+[![Code coverage](https://img.shields.io/codecov/c/github/transpiler-mate/cwl2mcp/develop?logo=codecov)](https://app.codecov.io/gh/transpiler-mate/cwl2mcp/tree/develop)
+
+A Transpiler Mate plugin deriving MCP tool definitions from parsed CWL v1.0–v1.2
+processes. CWL is authoritative for value structure; EOAP `mcp:Tool` supplies
+agent-facing metadata. This package does not execute CWL or run an MCP server.
+
+## Installation and use
+
+```bash
+python -m pip install './cwl2mcp[cli]'
+transpiler-mate cwl2mcp --output tool.json 'workflow.cwl#main'
+transpiler-mate cwl2mcp --output tools.json workflow.cwl
+```
+
+The current runtime requires document-level schema.org application metadata
+(name, description, dateCreated, license, softwareVersion, softwareHelp, publisher
+and author) before invoking plugins. The complete example and graph fixture show
+this metadata. The Python API does not require it.
+
+The runtime resolves imports and selects processes. A `#process` selection writes
+one MCP Tool object. Without a fragment, output is an object mapping the runtime's
+process IDs to tool definitions, including workflows, CommandLineTools and
+ExpressionTools. This mapping is an export container, not an MCP `tools/list`
+response. JSON keys are sorted, output ends with a newline, and parent directories
+are created. Conversion completes before an existing file is overwritten.
+
+```python
+from cwl_utils.parser import load_document_by_uri
+from cwl2mcp.converter import to_mcp_tool
+
+process = load_document_by_uri('file:///absolute/path/workflow.cwl')
+# Select one process first if the loader returned a list.
+tool = to_mcp_tool(process)
+print(tool.model_dump_json(by_alias=True, exclude_none=True, indent=2))
+```
+
+## Documentation
+
+The documentation follows Diátaxis and is published at
+<https://Transpiler-Mate.github.io/cwl2oci/>:
+
+- tutorials for guided learning;
+- how-to guides for specific tasks;
+- reference for the exact plugin and output contracts;
+- explanation for architecture and design context.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Submit issues at
+<https://github.com/Transpiler-Mate/cwl2oci/issues>.
+
+## License
+
+[![Apache License, Version 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)

cwl2mcp-0.1.0/docs/explanation/architecture.md

@@ -0,0 +1,72 @@
+# Architecture and data flow
+
+```text
+transpiler-mate-runtime
+  resolves CWL, prepares metadata, selects processes, validates options
+        |
+        v
+cwl2mcp plugin
+  loads the first matching Tool hint
+  delegates input/output schema conversion to cwl2ogc
+  constructs a generated McpTool model
+  serializes one Tool or a process-ID mapping
+        |
+        v
+tools.json
+```
+
+The runtime owns document loading and plugin discovery. The
+[plugin](../../src/cwl2mcp/plugin.py) writes JSON; the
+[converter](../../src/cwl2mcp/converter.py) returns a Tool without performing file
+I/O. An [MCP server](../how-to/use-with-mcp.md) must supply execution and protocol
+handling separately.
+
+## Two schema boundaries
+
+[schemas/hints.yaml](../../schemas/hints.yaml) is a Schema Salad extension of
+CWL. Its generated [mcp_hint.py](../../src/cwl2mcp/mcp_hint.py) validates custom
+hint mappings. Imported CWL and Salad classes are reused from `cwl-utils` and
+`schema-salad`. The generator uses `Any` constructor annotations; validation
+occurs in `fromDoc()`, not in those annotations.
+
+[schemas/mcp-tool.yaml](../../schemas/mcp-tool.yaml) defines the project's MCP
+Tool authoring profile. Its generated [mcp_tool.py](../../src/cwl2mcp/mcp_tool.py)
+contains Pydantic models. This profile is distinct from the official protocol
+schema. Constructing `McpTool` validates model fields but does not execute the
+embedded JSON Schemas against arguments or results.
+
+The converter preserves the literal hint name after Salad validation because
+Salad's shared `name` predicate otherwise applies document-relative identifier
+expansion. Input/output schema conversion uses the pinned `cwl2ogc` dependency;
+its generated schemas are copied without a separate artifact-receipt layer.
+
+## Regeneration
+
+Run the configured tasks from the repository root:
+
+```sh
+task generate_mpc_hint
+task generate_mpc_tool
+task generate_schema_doc
+```
+
+The `mpc` spelling is the current task name. The Tool task invokes the shared
+Terradue `json:create_models` task; the hint tasks use Schema Salad. See
+[Taskfile.yaml](../../Taskfile.yaml). Change source schemas and regenerate rather
+than editing generated classes or the [HTML hint reference](../reference/hints_schema.html).
+
+## Verification
+
+[Runtime integration tests](../../tests/test_runtime_crosswalk.py) exercise real
+CLI discovery and exported JSON. Assertions cover the current scalar URI/DateTime projection, metadata keys,
+selected-process and document exports, and deterministic serialization. The
+[hint schema tests](../../tests/test_hint_schema.py) cover the title and nested
+annotation handling. Run `task quality:pre-commit:run` for the complete quality gate. The test
+environments install JSON Schema format validators so malformed URI and
+date-time values are rejected.
+
+The hint-generation task applies reviewed Ruff rewrites and formatting after
+code generation. Generated loader complexity and schema-shaped signatures have
+file-specific Ruff exceptions; the upstream abstract-loader registration has a
+narrow mypy exception. Other checks remain enabled. See the comments in
+[pyproject.toml](../../pyproject.toml) for these generated-code boundaries.

cwl2mcp-0.1.0/docs/explanation/index.md

@@ -0,0 +1,4 @@
+# Explanation
+
+Read [Architecture and data flow](architecture.md) for the boundaries between
+the runtime, hint loader, schema converter, generated models, and MCP server.

cwl2mcp-0.1.0/docs/how-to/configure-output.md

@@ -0,0 +1,39 @@
+# Configure output and metadata keys
+
+From the repository root:
+
+```sh
+transpiler-mate cwl2mcp \
+  --output build/tool.json \
+  --meta-prefix org.example/mcp \
+  tests/examples/eoap.cwl#main
+```
+
+`--output` defaults to `tools.json`. Missing parent directories are created;
+existing files are replaced after successful conversion. JSON keys are sorted,
+indentation is two spaces, and the file ends with a newline.
+
+`--meta-prefix` defaults to `io.github.transpiler-mate/cwl2mcp`, users can customize it keeping in mind MCP’s `_meta` naming rules distinguish two parts:
+
+| Part | Rules |
+|---|---|
+| Optional prefix, before `/` | Dot-separated labels; reverse DNS is recommended. Labels start with a letter, end with a letter or digit, and may contain internal hyphens. |
+| Name, after `/` | May contain alphanumerics, hyphens, underscores, and dots. A nonempty name must start and end with an alphanumeric character. |
+
+The command above
+produces these custom keys when their values are nonempty:
+
+- `org.example/mcp-aliases`
+- `org.example/mcp-use-when`
+- `org.example/mcp-do-not-use-when`
+
+The suffixes use underscores. Empty lists and empty strings are omitted.
+
+Use `tests/examples/eoap.cwl#main` to export one Tool. Omit `#main` to export an
+object mapping process IDs to Tool definitions. This mapping is not an MCP
+`tools/list` response.
+
+For host integrations, construct `Cwl2McpOptions(output=Path("build/tool.json"),
+meta_prefix="org.example/mcp")` and pass it to the plugin registration's
+`execute(context, options)` method. See the [API reference](../reference/api.md)
+and [crosswalk](../reference/crosswalk.md).

cwl2mcp-0.1.0/docs/how-to/index.md

@@ -0,0 +1,7 @@
+# How-to guides
+
+- [Install the plugin and runtime](install.md).
+- [Configure output and metadata keys](configure-output.md).
+- [Use definitions in an MCP server](use-with-mcp.md).
+
+For a complete first run, follow the [tutorial](../tutorials/first-steps.md).

cwl2mcp-0.1.0/docs/how-to/install.md

@@ -0,0 +1,32 @@
+# Install cwl2mcp
+
+Use Python 3.10 or newer. From this repository's root, install the plugin and its
+runtime extra into the same environment:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install '.[cli]'
+transpiler-mate cwl2mcp --help
+```
+
+For editable development, use `python -m pip install -e '.[cli,test]'` instead.
+Dependencies are declared in [pyproject.toml](../../pyproject.toml); installation
+normally requires network access.
+
+The package installs a plugin entry point, not a standalone `cwl2mcp` executable.
+`transpiler-mate-runtime` provides the `transpiler-mate` command.
+
+Verify the registration and the imported source:
+
+```sh
+python -c "from cwl2mcp.plugin import cwl2mcp; print(cwl2mcp.name)"
+python -c "import cwl2mcp; print(cwl2mcp.__file__)"
+```
+
+The first command prints `cwl2mcp`. If a traceback points to an older installed
+copy, reinstall with the interpreter belonging to that CLI environment or use
+an editable installation. Regenerating models in a checkout does not update a
+separate installation automatically.
+
+Continue with the [first tool tutorial](../tutorials/first-steps.md).

cwl2mcp-0.1.0/docs/how-to/use-with-mcp.md

@@ -0,0 +1,22 @@
+# Use definitions in an MCP server
+
+Generate a selected Tool using the [runtime tutorial](../tutorials/first-steps.md).
+An MCP server can then use that definition when advertising its tools. For a
+whole-document export, take the values of the process-ID mapping first.
+The plugin's JSON is not itself a protocol response.
+
+The server is responsible for listing tools, handling calls, validating
+arguments, executing the workflow, and returning results. See the
+[MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+for the protocol messages and result contract.
+
+Validate incoming arguments against the generated `inputSchema` and returned
+objects against `outputSchema`. Enable a JSON Schema format checker if URI and
+date-time formats should be enforced. The generated EOAP example expects scalar
+URI and timestamp strings; an adapter must map them back to CWL record-shaped
+values if its runner requires those records. The plugin supplies no execution
+adapter.
+
+Tool annotations describe intended behavior and do not grant authorization.
+Discovery aliases in `_meta` do not register additional callable names.
+See the [crosswalk](../reference/crosswalk.md) for the exact exported shapes.

cwl2mcp-0.1.0/docs/how-to/use-with-oras.md

@@ -0,0 +1,7 @@
+# MCP output and OCI annotations
+
+`cwl2mcp` produces MCP Tool definitions, not ORAS manifest annotations. The old
+ORAS instructions on this page belonged to a different plugin.
+
+Continue with [using definitions in an MCP server](use-with-mcp.md),
+[output configuration](configure-output.md), or the [documentation index](../index.md).

cwl2mcp-0.1.0/docs/index.md

@@ -0,0 +1,20 @@
+# CWL to MCP
+
+`cwl2mcp` converts parsed CWL processes into MCP Tool definitions and writes them
+as JSON through `transpiler-mate-runtime`. It does not execute CWL or start an
+MCP server.
+
+## Start here
+
+- [Install the plugin and runtime](how-to/install.md).
+- [Generate your first tool definition](tutorials/first-steps.md).
+- [Configure output and metadata keys](how-to/configure-output.md).
+- [Use the exported definitions in an MCP server](how-to/use-with-mcp.md).
+- Look up the [CWL-to-MCP crosswalk](reference/crosswalk.md),
+  [Python and plugin API](reference/api.md), and
+  [generated hint reference](reference/hints_schema.html).
+- Read about the [architecture](explanation/architecture.md).
+
+Python 3.10 or newer is required. The runtime discovers the installed plugin via
+its `transpiler_mate.plugins` entry point. See the
+[project configuration](../pyproject.toml) for dependencies and quality checks.

cwl2mcp-0.1.0/docs/reference/api.md

@@ -0,0 +1,57 @@
+# Plugin and Python API
+
+## Registration and options
+
+The [plugin implementation](../../src/cwl2mcp/plugin.py) registers
+`cwl2mcp.plugin:cwl2mcp` as `cwl2mcp` in the `transpiler_mate.plugins` group.
+The decorated object is a plugin registration; a host invokes
+`cwl2mcp.execute(context, options)`.
+
+`Cwl2McpOptions` rejects unknown fields:
+
+| Option | Python type | Default |
+|---|---|---|
+| `output` | `pathlib.Path` | `tools.json` |
+| `meta_prefix` | `str` | `io.github.transpiler-mate/cwl2mcp` |
+
+The runtime exposes these as `--output` and `--meta-prefix`. See
+[output configuration](../how-to/configure-output.md).
+
+When `context.process_id` is set, the plugin converts `context.resolved_process`.
+Otherwise it converts each process in `context.document` and writes a mapping
+keyed by the runtime's process IDs. The runtime also prepares software application
+metadata, but this plugin reads tool metadata from the CWL process and hint.
+
+## Direct conversion
+
+```python
+from pathlib import Path
+from cwl_utils.parser import Process, load_document_by_uri
+from cwl2mcp.converter import to_mcp_tool
+
+process = load_document_by_uri(
+    Path("tests/examples/eoap.cwl").resolve().as_uri() + "#main"
+)
+assert isinstance(process, Process)
+tool = to_mcp_tool(process, meta_prefix="example.org/mcp")
+payload = tool.model_dump(by_alias=True, exclude_none=True)
+```
+
+`to_mcp_tool(process, meta_prefix)` returns the generated `McpTool` Pydantic model
+and does not write files. `meta_prefix` is required in the Python API.
+`get_tool_hint(process)` in [converter.py](../../src/cwl2mcp/converter.py) returns
+the first matching `Tool` hint, or `None`. It accepts parsed hints and validates
+mapping hints using the generated Salad model.
+
+## Errors
+
+- Malformed hint mappings raise Schema Salad `ValidationException`.
+- Invalid tool fields raise Pydantic `ValidationError` during conversion.
+- Schema conversion can raise errors from `cwl2ogc`.
+- The plugin wraps conversion-time `ValueError` as `PluginFailureError`.
+  Salad validation errors are not wrapped by that handler.
+- File-system `OSError` is wrapped as `PluginExecutionError`.
+
+Conversion finishes before the destination is opened. Parent directories are
+created. Writing is not an atomic replacement: an I/O failure after opening can
+leave a partial file. See the [crosswalk](crosswalk.md) for serialization details.

cwl2mcp-0.1.0/docs/reference/crosswalk.md

@@ -0,0 +1,138 @@
+# CWL to MCP crosswalk
+
+This page describes the current [converter](../../src/cwl2mcp/converter.py) and
+[export plugin](../../src/cwl2mcp/plugin.py). The plugin generates Tool definitions;
+it does not execute CWL, provide an MCP server, or generate artifact receipts.
+
+## Process fields
+
+| CWL source | Resulting JSON | Current mapping |
+|---|---|---|
+| Nonempty `mcp:Tool.name`, otherwise process `id` | `name` | A mapping hint's literal name is preserved. The fallback process ID is not normalized. |
+| Nonempty `mcp:Tool.title`, otherwise `label` | `title` | Omitted when neither supplies a nonempty value. |
+| Nonempty process `doc` | `description` | Passed directly to the model. There is no hint description override or appended guidance. |
+| `inputs` | `inputSchema` | Result of `BaseCWLtypes2OGCConverter.get_inputs_json_schema()`. |
+| `outputs` | `outputSchema` | Result of `BaseCWLtypes2OGCConverter.get_outputs_json_schema()`. |
+| `mcp:Tool.annotations` | `annotations` | Copies all four behavioral booleans, including `false`. Omitted when no hint is found. |
+| Nonempty `mcp:Tool.aliases` | `_meta["<prefix>-aliases"]` | Preserves the list. |
+| Nonempty `mcp:Tool.useWhen` | `_meta["<prefix>-use_when"]` | Preserves the string without changing `description`. |
+| Nonempty `mcp:Tool.doNotUseWhen` | `_meta["<prefix>-do_not_use_when"]` | Preserves the string without changing `description`. |
+
+The default prefix is `transpiler-mate.github.io/cwl2mcp`; configure it with
+`--meta-prefix`. The converter always supplies `_meta`, even when it is `{}`.
+See [output configuration](../how-to/configure-output.md).
+
+The generated [MCP model](../../src/cwl2mcp/mcp_tool.py) requires a name of 1–128
+ASCII letters, digits, underscores, dots, or hyphens. A URI-valued fallback ID can
+therefore fail validation. Supply an explicit callable name in the hint.
+`description` must be a string; lists of CWL documentation paragraphs are not
+joined by the converter and can fail model validation.
+
+## Hint selection and validation
+
+Only `process.hints` is searched. The first matching Tool is used; later matches
+are not rejected. `requirements` is not searched for MCP hints. Class names may
+be full URIs or use any process namespace prefix bound to
+`https://eoap.github.io/cwl-mcp-extension#`.
+
+A complete hint for the [EOAP example](../../tests/examples/eoap.cwl) is:
+
+```yaml
+hints:
+  agent:Tool:
+    name: inspect_source
+    title: Inspect Source
+    aliases: [inspect a spatial source]
+    useWhen: the user needs to inspect a spatial source.
+    doNotUseWhen: the user needs data modification.
+    annotations:
+      readOnlyHint: true
+      destructiveHint: false
+      idempotentHint: true
+      openWorldHint: false
+```
+
+The document must bind `agent` to the extension namespace. See the
+[hint source schema](../../schemas/hints.yaml) and
+[generated hint reference](hints_schema.html) for field definitions.
+`title` is optional. `aliases`, `useWhen`, `doNotUseWhen`, `annotations`, and all
+four annotation booleans are required by the current mapping loader; empty
+aliases/guidance values are allowed but omitted from `_meta`. The schema declares
+`name` as an identifier string; Salad can synthesize a missing identifier, so an
+explicit MCP-compatible name should always be provided.
+
+`annotations.class` may be omitted. If supplied, it must identify `Annotations`.
+`Tool.description` is not a declared hint field and is rejected. Unknown
+unqualified fields and invalid field values raise validation errors. Already
+constructed Tool instances are returned unchanged rather than revalidated.
+
+## Parameter schemas and EOAP conversion
+
+The project pins `cwl2ogc` in [pyproject.toml](../../pyproject.toml). Its schemas
+are copied directly into the Tool; this plugin does not add parameter titles,
+join parameter documentation, register extra formats, or provide a custom File
+receipt schema. Inspect the emitted schema for the resulting types, defaults,
+required fields, and definitions.
+
+For the current EOAP example, the input schema contains definitions equivalent
+to these excerpts:
+
+```json
+{
+  "source": {"type": "string", "format": "uri"},
+  "timestamp": {"type": "string", "format": "date-time"}
+}
+```
+
+Properties refer to them through `$ref` values such as `#/$defs/source`.
+URI and DateTime records are flattened into scalar strings. The GeoJSON Point
+remains an object requiring `type`, `coordinates`, and `bbox`. Its coordinate and
+bounding-box values are arrays of numbers. The output schema uses corresponding
+`source_result`, `timestamp_result`, and `point_result` fields.
+
+Thus the [CWL arguments fixture](../../tests/examples/arguments.json), which
+wraps URI and timestamp values in `{"value": ...}`, needs adaptation before it
+can satisfy the exported MCP input schema. See the
+[tutorial](../tutorials/first-steps.md) for a matching MCP argument object.
+Format validation requires a format-aware JSON Schema validator.
+
+## Example metadata output
+
+The EOAP example produces this metadata excerpt, alongside its input and output
+schemas:
+
+```json
+{
+  "name": "inspect_source",
+  "title": "Inspect Source",
+  "description": "Return a source URI, timestamp and GeoJSON point without changing their records.",
+  "annotations": {
+    "readOnlyHint": true,
+    "destructiveHint": false,
+    "idempotentHint": true,
+    "openWorldHint": false
+  },
+  "_meta": {
+    "transpiler-mate.github.io/cwl2mcp-aliases": ["inspect a spatial source"],
+    "transpiler-mate.github.io/cwl2mcp-use_when": "the user needs to inspect a spatial source.",
+    "transpiler-mate.github.io/cwl2mcp-do_not_use_when": "the user needs data modification."
+  }
+}
+```
+
+## Export container
+
+| CLI source | Export |
+|---|---|
+| `tests/examples/eoap.cwl#main` | One MCP Tool object. |
+| `tests/examples/eoap.cwl` | A mapping such as `{"main": <Tool>}`. |
+
+JSON aliases are used and fields whose value is `None` are omitted. Keys are
+sorted, indentation is two spaces, and output ends with a newline. The plugin
+creates parent directories and completes conversion before opening the output
+file. It does not perform an atomic file replacement.
+
+The runtime requires software application metadata before plugin execution;
+the direct [Python conversion API](api.md) only needs a parsed process and a
+metadata prefix. A whole-document export is a plugin container, not an MCP
+`tools/list` response. See [using definitions in MCP](../how-to/use-with-mcp.md).