TMF MCP Builder

Workflow (decision tree)

1. Choose the product shape

   • Wrap a real TMF API: Implement only the MCP server + HTTP client; no mock server.
   • Generate a full dev sandbox: Mock server (FastAPI) + HTTP client + MCP server that proxies to the mock.

2. Choose the MCP framework (Python)

   • Use the official mcp Python SDK + FastMCP (recommended): implement tools directly with @mcp.tool and choose the transport (stdio or HTTP) based on your deployment needs.

3. Choose the implementation approach

   • Hand-build: Use this skill as a checklist and build the server normally.
   • LLM-assisted generation (this repo): Use tmf_llm_agent.py to generate a starter implementation from an OpenAPI YAML, then tighten tool schemas and edge cases.

Conventions (TMF-specific)

Naming

• Files (recommended for generated outputs)
  • tmf###_mock_server.py
  • tmf###_client.py
  • tmf###_mcp_server.py
  • run_mock_server.py, run_mcp_server.py
• Tools
  • Use snake_case with TMF prefix: tmf{tmf_number}_{action}_{resource}
  • Standard actions: list, get, create, patch (or update), delete, plus health_check

Input ergonomics: create/update tools

For TMF create operations, prefer field-level parameters (LLM-friendly) and rebuild the TMF JSON internally.

• Read references/resource-creation-guidelines.md before implementing create_* tools.
• Avoid a single blob parameter like customer: dict unless you also provide ergonomic field inputs.

OpenAPI-driven behavior

When generating mock behavior from TMF OpenAPI:

• Treat $ref resolution as mandatory for realistic sample payloads.
• Treat allOf as mandatory (TMF uses it heavily). Merge allOf schemas (including cases where type: object and allOf both exist).
• Identify main resources from the path set (e.g., /customer, /product, /service) and implement full CRUD for those first.

/hub and event endpoints

• Implement /hub endpoints only if required by the spec or your use case.
• If you implement them, keep them consistent: create/get/delete subscription, and store subscriptions in-memory for mocks.

Practical build steps (Python)

1. Inventory the spec

   • Find the correct TMF OpenAPI YAML in https://github.com/tmforum-apis (users must pick the TMFxxx spec/version that matches their API).
   • Determine base paths, main resources, and required operations.
   • Extract required fields for create/patch input models.

2. Ensure tmf_commons is available

   • Copy assets/tmf_commons into your project root (or otherwise ensure it is importable). You can use scripts/copy_tmf_commons.py --dest <project-root>.

3. Implement the HTTP client

   • Use httpx.AsyncClient.
   • Provide consistent error handling and timeouts.

4. Implement the mock server (optional)

   • Use in-memory storage keyed by resource.
   • Pre-populate sample objects.
   • Support: list (filter/paginate), get by id, create, patch, delete.

5. Implement the MCP server

   • Expose tools for the main resources.
   • Make list tools pageable (limit, offset or cursor).
   • Return predictable structured JSON (and optionally a markdown view if your framework supports it).

6. Validate tool usability

   • Tool names are discoverable.
   • Create/update inputs are not "blob-only".
   • Errors are actionable.

7. Add an evaluation set (recommended)

   • Create 10 read-only questions that require multiple tool calls.
   • If you need a template, follow the approach in the general mcp-builder evaluation guidance.

8. Generate README-TMFxxxx (required)

   • Create a README-TMF####.md file as the final step (after servers and tools are implemented).
   • Use the TMF number from the OpenAPI spec (for TMF620, generate README-TMF620.md).
   • Include: overview, endpoints/tools list, run instructions (mock server + MCP server), and environment variables.

9. Add requirements.txt (required)

   • Create a requirements.txt in the output folder that lists runtime dependencies.
   • Include at least: fastapi, uvicorn, httpx, mcp, pyyaml.

Bundled assets

• tmf_commons: copy ssets/tmf_commons into your project root when you want the shared mock server utilities (or run scripts/copy_tmf_commons.py --dest ).

References (load as needed)

• Bundled assets: ssets/tmf_commons (copy into your project root if you need the shared mock server utilities).

• All-in-one generator prompt: references/TMF_MCP_SERVER_CREATION_PROMPT_all-in-one.md

• Libraries-based generator prompt: references/TMF_MCP_SERVER_CREATION_PROMPT_libraries.md

• Create/update input rule (important): references/resource-creation-guidelines.md