Remove teddi-mcp package (moved to separate repository)

node = "latest"

bun = "latest"

[env]

GITLAB_HOST = "forge.3gpp.org"

[settings.npm]

package_manager = "bun"

run = [

    'cls',

    'bun x add-mcp -y -a {{usage.ai_agent}} "grepai mcp-serve"',

    'bun x add-mcp -y -a {{usage.ai_agent}} -n teddi-mcp "uv run -m teddi_mcp server"',

    'bun x add-mcp -y -a {{usage.ai_agent}} -n cytoscnpy-mcp "cytoscnpy mcp-server"'

]

| `src/tdoc_crawler/` | Core crawler library |

| `src/tdoc_crawler/cli/` | CLI patterns |

| `packages/tdoc-ai/` | AI document processing |

| `packages/teddi-mcp/` | TEDDI MCP server |

| `packages/teddi-mcp/` | ~~TEDDI MCP server~~ (moved to separate repo) |

| `packages/convert-lo/` | LibreOffice conversion |

# Install with AI features (optional)

uv add tdoc-crawler[ai]

# Install with TEDDI MCP features (optional)

uv add tdoc-crawler[teddi]

# AI features are provided by the optional `tdoc-ai` extension package

# and installed automatically via the extra above.

# Or install from source

git clone https://forge.3gpp.org/rep/reimes/tdoc-crawler.git

cd tdoc-crawler

uv sync

# Enable optional AI extension in source checkout

uv sync --extra ai

# Enable optional TEDDI MCP extension in source checkout

uv sync --extra teddi

```

### Using pip (not recommended)

# teddi-mcp

FastMCP 3.0 server for ETSI TEDDI (TErms and Definitions Database Interactive).

## Quick Start

```bash

uv pip install -e .

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

teddi-mcp serve  # Start MCP server

```

**Key Files:**

- `models.py` — Pydantic models

- `client.py` — `TeddiClient` with Protocol abstraction

- `server.py` — FastMCP 3.0 server (stdio)

- `parser.py` — HTML parsing with TB grouping

- `cli.py` — Typer CLI (non-MCP)

## Key Design Patterns

### Protocol-Based Abstraction

`TeddiSource` protocol enables mocking/swapping TEDDI sources:

```python

class TeddiSource(Protocol):

    async def search_terms(self, request: SearchRequest) -> SearchResponse: ...

    async def get_available_technical_bodies(self) -> list[TechnicalBody]: ...

    async def fetch_document(self, url: str) -> bytes: ...

```

### HTTP Caching

All requests use `create_cached_teddi_session()`:

- SQLite: `.cache/teddi_http.sqlite3`

- TTL: 2 hours (refresh on access)

- Auto-retries: 429, 500, 502, 503, 504

### TB Grouping in Parser

TEDDI results have nested tables. Parser handles TB inheritance:

- Empty TB cell inherits previous TB value

- Results grouped by technical body

### Dual API: MCP + CLI

Both expose identical tools:

- `search_term()` — query with filters

- `list_technical_bodies()` — list TBs

- `fetch_document()` — retrieve content (MCP-only)

## Data Models

See `models.py` for complete definitions:

- **Enums:** `SearchIn`, `SearchPattern`, `TechnicalBody`

- **Data Classes:** `DocumentRef`, `TermResult`

## TEDDI Endpoint

**POST** `https://webapp.etsi.org/Teddi/search`

**Parameters:** `term`, `searchin`, `searchpattern`, `technicaldiebody`

**Response:** HTML table (parsed by `parser.py`)

## Testing

```bash

uv run pytest tests/teddi_mcp/ -v

uv run pytest tests/teddi_mcp/ --cov=teddi_mcp

```

**Test structure:** `test_models.py`, `test_parser.py`, `test_client.py`, `test_http_client.py`, `test_cli.py`, `test_server.py`

## Implementation Notes

1. **TEDDI HTML-Driven:** Endpoint reverse-engineered. Parser may need updates if TEDDI UI changes.

2. **Async-First:** All core methods async. Use `asyncio.run()` for sync wrappers.

3. **Cache Validation:** Tests auto-cache in `tests/.cache/teddi_http.sqlite3`.

## Adding Features

### New Search Filter

1. Define enum in `models.py`

2. Update `SearchRequest` dataclass

3. Update HTTP call in `client.py`

4. Update CLI in `cli.py`

5. Update MCP server in `server.py`

6. Add tests

# TEDDI-MCP: FastMCP Server for ETSI TEDDI

A FastMCP 3.0 server that wraps ETSI's TErms and Definitions Database Interactive (TEDDI) for AI agent integration and command-line usage.

## Features

- **FastMCP 3.0 Server**: Expose TEDDI search as an MCP tool for AI agents (Claude, etc.)

- **CLI Interface**: Search TEDDI from the command line with table, JSON, ISON, and TOON output

- **HTTP Caching**: Automatic hishel-based caching of TEDDI responses (2-hour TTL)

- **TB Grouping**: Smart parsing of sub-table results with technical body grouping logic

- **Type-Safe**: Full Pydantic models and type hints throughout

- **Async-First**: Built on asyncio for performance

## Quick Start

### Installation

```bash

cd src/teddi-mcp

uv pip install -e .

```

### CLI Usage

```bash

# Search for a term

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

# List available technical bodies

teddi-mcp search list-bodies

# JSON output

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

# ISON output (token-optimized)

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

# TOON output (token-optimized)

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

# Filter by technical bodies

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

```

### MCP Server

```bash

# Start the MCP server (stdio)

teddi-mcp server

```

Then configure your AI agent client (e.g., Claude) to use this server:

```json

{

  "mcpServers": {

    "teddi": {

      "command": "teddi-mcp",

      "args": ["server"]

    }

  }

}

```

## Architecture

- **models.py**: Pydantic data models (SearchIn, SearchPattern, TechnicalBody enums)

- **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

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

## Testing

```bash

# Run all tests

uv run pytest tests/teddi_mcp/ -v

# Run with coverage

uv run pytest tests/teddi_mcp/ --cov=teddi_mcp --cov-report=term-missing

# Run specific test

uv run pytest tests/teddi_mcp/test_parser.py -v

```

## Development

See [AGENTS.md](AGENTS.md) for detailed development guidelines including:

- Protocol-based abstraction patterns

- HTTP caching with hishel

- Sub-table parsing with TB grouping

- Dual API design (MCP + CLI)

- Adding new features

## License

MIT