---
slug: "tmf620-mcp服务器"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/oopsyz/mcp@master/README.md"
repo: "https://github.com/oopsyz/mcp"
source_file: "README.md"
branch: "master"
---
# TMF620 CLI vs MCP

This repo exposes the TMF620 command layer through two interfaces:

- a compact HTTP CLI API for progressive discovery
- an MCP server used here as a reference surface for benchmarking and testing

Documentation index: [docs/README.md](https://github.com/oopsyz/mcp/blob/HEAD/docs/README.md)

The engine-specific [oa-engine CLI-over-HTTP control-plane profile](https://github.com/oopsyz/oa-engine/blob/main/docs/oa-engine-http-cli-spec.md)
is maintained in the `oa_engine` repository; this repository owns the generic
CLI-style HTTP protocol.

Repository layout:

- `tmf620/` - TMF620 mock API, shared client, commands, server, and benchmark
- `tests/` - pytest-discoverable wrappers plus standalone conformance, API, and edge-case scripts
- `docs/` - long-form protocol docs and guides
- `benchmarks/` - benchmark scripts and baseline data
- `scripts/` - repo entrypoint scripts
- `specs/` - source OpenAPI and protocol specs
- `tmf620/config/` - TMF620 runtime configuration files
- `DOMAIN.md` / `AGENTS.md` - repo-level contracts and agent instructions
- `tmf620/config/config.json` - canonical runtime data and configuration

The TMF620 sample implementation is kept in a service-local folder so it can be deployed independently of other systems.

The CLI API is the cheaper discovery path for agents that only need one command branch at a time. The MCP server is retained here as a comparison point for discovery payloads, tool-list size, and latency measurements.

The practical reasons to keep both are:

- compact discovery: agents can start with `GET /cli/tmf620/catalogmgt` instead of ingesting the full MCP tool list up front
- progressive help: agents can expand one command branch at a time with `help`
- stronger MCP contracts: MCP tools now expose explicit schemas instead of a generic `args` object
- simpler automation: `curl` works well for both humans and agents, especially when the command surface is already structured
- one shared command layer: the same command definitions back the HTTP CLI API, the MCP reference surface, and the benchmark

TMF620 Product Catalog Management with three layers:

- a mock TMF620 API
- a shared Python client
- two adapters over that client: HTTP CLI API and MCP

This keeps the operational logic in one place while supporting HTTP and MCP adapters over the same TMF620 command set.

Request paths:

- HTTP CLI API -> `tmf620/server.py` -> `tmf620/commands.py` -> `tmf620/core.py` -> TMF620 API
- MCP client -> `tmf620/server.py` -> `tmf620/core.py` -> TMF620 API

## Components

### 1. Mock TMF620 API

File: `tmf620/mock_api.py`

- FastAPI-based TMF620 mock server
- sample catalogs, offerings, and specifications
- Swagger docs

### 2. Shared TMF620 Client

File: `tmf620/core.py`

- config loading
- HTTP request handling
- health checks
- generic CRUD helpers for TMF620 resources
- catalog, category, offering, price, specification, import/export job, and hub operations

### 3. Shared Command Layer

File: `tmf620/commands.py`

- canonical TMF620 command registry
- machine-readable discover/help payloads
- structured command invocation shared by shell and HTTP adapters

### 4. MCP + HTTP CLI Adapter

File: `tmf620/server.py`

- FastAPI + the official MCP SDK (`FastMCP`)
- exposes `/cli/tmf620/catalogmgt` as the primary HTTP CLI endpoint
- keeps `/cli` and `/api/cli` as compatibility aliases
- exposes explicit MCP tools for benchmarking and test coverage
- delegates HTTP CLI requests into `tmf620/commands.py`
- delegates MCP tools into the shared command layer

Use the TMF620 compose file for the mock API + MCP server.

```bash
docker compose -f docker-compose.yml up --build
```

TMF620 stack exposes:

- mock API at `http://localhost:8801/tmf-api/productCatalogManagement/v5`
- MCP transport at `http://localhost:7701/mcp`
- HTTP CLI API at `http://localhost:7701/cli/tmf620/catalogmgt`

The containers use environment overrides rather than rewriting config files. Set them in the matching compose file, or use a `.env` file with Docker Compose:

- `TMF620_API_URL`

## Without Docker

Use this path for local development with `uv`.

### Install dependencies

```bash
uv sync
```

### Start the mock API

```bash
uv run tmf620-mock-server
```

### Use the HTTP CLI API

```bash
curl http://localhost:7701/cli/tmf620/catalogmgt
curl "http://localhost:7701/cli/tmf620/catalogmgt?verbose=true"
curl -X POST http://localhost:7701/cli/tmf620/catalogmgt \
  -H "Content-Type: application/json" \
  -d '{"command":"help","args":{"command":"offering patch"}}'
curl -X POST http://localhost:7701/cli/tmf620/catalogmgt \
  -H "Content-Type: application/json" \
  -d '{"command":"catalog list","args":{"lifecycle_status":"Active","limit":5}}'
```

### Start the MCP server

```bash
uv run tmf620-mcp-server
```

Default MCP server URL:

```text
http://localhost:7701
```

## Configuration

`tmf620/config/config.json` is used by both the HTTP CLI API and MCP server:

```json
{
  "mcp_server": {
    "host": "localhost",
    "port": 7701,
    "name": "TMF620 Product Catalog API"
  },
  "tmf620_api": {
    "url": "http://localhost:8801/tmf-api/productCatalogManagement/v5"
  }
}
```

Environment variables override file values at runtime:

- `TMF620_API_URL`

You can also override the config path with `TMF620_CONFIG_PATH`.

## HTTP CLI Commands

```bash
# Discovery
curl http://localhost:7701/cli/tmf620/catalogmgt
curl "http://localhost:7701/cli/tmf620/catalogmgt?verbose=true"
curl -X POST http://localhost:7701/cli/tmf620/catalogmgt \
  -H "Content-Type: application/json" \
  -d '{"command":"help","args":{"command":"offering"}}'

# Read/list commands
curl -X POST http://localhost:7701/cli/tmf620/catalogmgt \
  -H "Content-Type: application/json" \
  -d '{"command":"catalog list","args":{"limit":5}}'
curl -X POST http://localhost:7701/cli/tmf620/catalogmgt \
  -H "Content-Type: application/json" \
  -d '{"command":"catalog list","args":{"lifecycle_status":"Active","limit":5}}'

# Create/patch commands use JSON bodies because TMF620 resource payloads are wide
curl -X POST http://localhost:7701/cli/tmf620/catalogmgt \
  -H "Content-Type: application/json" \
  -d '{"command":"catalog create","args":{"body":{"name":"Business Catalog","lifecycleStatus":"Active"}}}'
```

## MCP Usage

Example Claude Desktop config:

```json
{
  "mcpServers": {
    "tmf620-mcp": {
      "command": "uv",
      "args": ["run", "tmf620-mcp-server"],
      "cwd": "/path/to/tmf620-mcp-server"
    }
  }
}
```

Available MCP tools:

- `tmf620_health`
- `tmf620_config`
- `tmf620_discover`
- one explicit tool per leaf command in `tmf620/commands.py`

## Testing

```bash
# Mock API
curl http://localhost:8801/tmf-api/productCatalogManagement/v5/productCatalog

# HTTP CLI API
curl http://localhost:7701/cli/tmf620/catalogmgt
curl -X POST http://localhost:7701/cli/tmf620/catalogmgt -H "Content-Type: application/json" -d '{"command":"catalog list","args":{}}'

# MCP server
curl http://localhost:7701/health

# Pytest suite
pytest tests
```

## Token Benchmark

Use the built-in benchmark to measure the live MCP tool payload alongside the compact HTTP CLI discovery flow:

```bash
uv run tmf620-benchmark token
uv run tmf620-benchmark token --output json
```

## Latency Benchmark

Use the latency benchmark when you want request-to-answer timing, not just invoke-only timing:

```bash
uv run tmf620-benchmark latency 30 --warmup 1
```

## Packaging

Console scripts exposed by `pyproject.toml`:

- `tmf620-mock-server`
- `tmf620-mcp-server`
- `tmf620-benchmark`