Commit fcaddae2 authored by Jan Reimes's avatar Jan Reimes
Browse files

feat(cli): update CLI commands and usage documentation 

* Refactor CLI commands for consistency across executables
* Enhance README and usage documentation with command equivalences
* Update pyproject.toml to reflect new CLI script structure
* Improve output format examples in documentation
parent 7413cfae

README.md

+36 −12
Original line number Diff line number Diff line
@@ -22,31 +22,54 @@ uv pip install -e . 


### CLI Usage



Three executables are available:



```bash

# Search for a term

teddi-mcp search term "QoS" --search-pattern exactmatch

# Full CLI (search + server)

teddi search-term "QoS" --pattern exactmatch

teddi list-bodies

teddi server



# Search-only CLI (equivalent to `teddi search-*`)

teddi-cli term "QoS" --pattern exactmatch

teddi-cli list-bodies



# MCP server only (equivalent to `teddi server`)

teddi-mcp

```



# List available technical bodies

teddi-mcp search list-bodies

**Equivalences:**



| Command | Equivalent |

|---------|------------|

| `teddi-mcp` | `teddi server` |

| `teddi-cli term ...` | `teddi search-term ...` |

| `teddi-cli list-bodies` | `teddi list-bodies` |



**Output formats:**



```bash

# Table output (default)

teddi search-term "QoS"



# JSON output

teddi-mcp search term "QoS" --output json

teddi search-term "QoS" --output json



# ISON output (token-optimized)

teddi-mcp search term "QoS" --output ison

teddi search-term "QoS" --output ison



# TOON output (token-optimized)

teddi-mcp search term "QoS" --output toon

teddi search-term "QoS" --output toon



# Filter by technical bodies

teddi-mcp search term "test" --technical-bodies "3gpp,etsi"

teddi search-term "test" --technical-bodies "3gpp,etsi"

```



### MCP Server



```bash

# Start the MCP server (stdio)

teddi-mcp server

teddi-mcp

```



Then configure your AI agent client (e.g., Claude) to use this server:
@@ -55,8 +78,7 @@ Then configure your AI agent client (e.g., Claude) to use this server: 
{

  "mcpServers": {

    "teddi": {

      "command": "teddi-mcp",

      "args": ["server"]

      "command": "teddi-mcp"

    }

  }

}
@@ -68,7 +90,9 @@ Then configure your AI agent client (e.g., Claude) to use this server: 
- **client.py**: Core TeddiClient with Protocol-based abstraction

- **parser.py**: HTML parsing with TB grouping logic

- **http_client.py**: HTTP session manager with hishel caching

- **cli.py**: Typer CLI interface

- **search_utils.py**: Shared search logic for CLI executables

- **cli.py**: Typer CLI for `teddi` executable (full CLI)

- **search_cli.py**: Typer CLI for `teddi-cli` executable (search-only)

- **server.py**: FastMCP 3.0 server implementation



## Testing

docs/index.md

+33 −11
Original line number Diff line number Diff line
@@ -27,31 +27,54 @@ uv pip install -e . 


### CLI Usage



Three executables are available:



```bash

# Search for a term

teddi-mcp search term "QoS" --search-pattern exactmatch

# Full CLI (search + server)

teddi search-term "QoS" --pattern exactmatch

teddi list-bodies

teddi server



# Search-only CLI (equivalent to `teddi search-*`)

teddi-cli term "QoS" --pattern exactmatch

teddi-cli list-bodies



# MCP server only (equivalent to `teddi server`)

teddi-mcp

```



# List available technical bodies

teddi-mcp search list-bodies

**Equivalences:**



| Command | Equivalent |

|---------|------------|

| `teddi-mcp` | `teddi server` |

| `teddi-cli term ...` | `teddi search-term ...` |

| `teddi-cli list-bodies` | `teddi list-bodies` |



**Output formats:**



```bash

# Table output (default)

teddi search-term "QoS"



# JSON output

teddi-mcp search term "QoS" --output json

teddi search-term "QoS" --output json



# ISON output (token-optimized)

teddi-mcp search term "QoS" --output ison

teddi search-term "QoS" --output ison



# TOON output (token-optimized)

teddi-mcp search term "QoS" --output toon

teddi search-term "QoS" --output toon



# Filter by technical bodies

teddi-mcp search term "test" --technical-bodies "3gpp,etsi"

teddi search-term "test" --technical-bodies "3gpp,etsi"

```



### MCP Server



```bash

# Start the MCP server (stdio)

teddi-mcp server

teddi-mcp

```



Then configure your AI agent client to use this server:
@@ -60,8 +83,7 @@ Then configure your AI agent client to use this server: 
{

  "mcpServers": {

    "teddi": {

      "command": "teddi-mcp",

      "args": ["server"]

      "command": "teddi-mcp"

    }

  }

}

docs/usage.md

+36 −13
Original line number Diff line number Diff line 
# Usage



## CLI Executables



Three executables are provided:



| Executable | Description | Equivalent |

|------------|-------------|------------|

| `teddi` | Full CLI: search commands + server | — |

| `teddi-cli` | Search commands only | `teddi search-*` |

| `teddi-mcp` | MCP server only (stdio) | `teddi server` |



**Command Equivalences:**



| Command | Equivalent |

|---------|------------|

| `teddi-mcp` | `teddi server` |

| `teddi-cli term ...` | `teddi search-term ...` |

| `teddi-cli list-bodies` | `teddi list-bodies` |



## CLI Commands



### Search Terms



```bash

# Basic search

teddi-mcp search term "QoS"

# Basic search (full CLI)

teddi search-term "QoS"



# Search (search-only CLI)

teddi-cli term "QoS"



# Exact match

teddi-mcp search term "QoS" --search-pattern exactmatch

teddi search-term "QoS" --pattern exactmatch



# Starting with

teddi-mcp search term "QoS" --search-pattern startingwith

teddi search-term "QoS" --pattern startingwith



# Search in definitions only

teddi-mcp search term "QoS" --search-in definitions

teddi search-term "QoS" --scope definitions



# Search in abbreviations only

teddi-mcp search term "QoS" --search-in abbreviations

teddi search-term "QoS" --scope abbreviations



# Filter by technical bodies

teddi-mcp search term "test" --technical-bodies "3gpp,etsi"

teddi search-term "test" --technical-bodies "3gpp,etsi"



# Output formats

teddi-mcp search term "QoS" --output table

teddi-mcp search term "QoS" --output json

teddi-mcp search term "QoS" --output ison

teddi-mcp search term "QoS" --output toon

teddi search-term "QoS" --output table

teddi search-term "QoS" --output json

teddi search-term "QoS" --output ison

teddi search-term "QoS" --output toon

```



### List Technical Bodies



```bash

teddi-mcp search list-bodies

teddi list-bodies

# or

teddi-cli list-bodies

```



### MCP Server



```bash

# Start the MCP server (stdio mode)

teddi-mcp server

teddi-mcp

```



## Output Formats

pyproject.toml

+5 −3
Original line number Diff line number Diff line
@@ -31,13 +31,15 @@ dev = [ 
    "pytest>=7.4.0",

    "pytest-asyncio>=0.21.0",

    "pytest-cov>=4.1.0",

    "ruff>=0.1.0",

    "ty>=0.1.0",

    "ruff",

    "ty",

    "undersort>=0.1.5",

]



[project.scripts]

teddi-mcp = "src.teddi_mcp.cli:app"

teddi = "teddi_mcp.cli:run"

teddi-mcp = "teddi_mcp.server:main"

teddi-cli = "teddi_mcp.search_cli:run"



[tool.hatch.build.targets.wheel]

packages = ["src/teddi_mcp"]