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

📝 docs: update documentation with improved formatting and consistency

parent 20fddc67

AGENTS.md

+11 −7
Original line number Diff line number Diff line
@@ -11,6 +11,7 @@ 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)
@@ -33,6 +34,7 @@ class TeddiSource(Protocol): 
### 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
@@ -40,12 +42,14 @@ All requests use `create_cached_teddi_session()`: 
### 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)
@@ -77,16 +81,16 @@ uv run pytest tests/teddi_mcp/ --cov=teddi_mcp 
## 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`.

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

1. **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
 
1. Update `SearchRequest` dataclass

1. Update HTTP call in `client.py`

1. Update CLI in `cli.py`

1. Update MCP server in `server.py`

1. Add tests

README.md

+1 −0
Original line number Diff line number Diff line
@@ -87,6 +87,7 @@ 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

docs/api.md

+1 −0
Original line number Diff line number Diff line
@@ -167,6 +167,7 @@ def parse_teddi_response(html: str) -> list[TermResult]: 
**POST** `https://webapp.etsi.org/Teddi/search`



**Parameters:**



- `qWhatToSearch`: Term to search

- `qWhereOption`: Search scope (1=abbreviations, 3=definitions, 2=both)

- `qWhatOption`: Match pattern (1=alloccurrences, 2=startingwith, 3=endingwith, 4=exactmatch)

docs/development.md

+15 −9
Original line number Diff line number Diff line
@@ -3,17 +3,20 @@ 
## Setup



1. Clone the repository:



   ```bash

   git clone https://forge.3gpp.org/rep/reimes/teddi-mcp.git

   cd teddi-mcp

   ```



2. Sync dependencies:

1. Sync dependencies:



   ```bash

   uv sync --all-extras

   ```



3. Install pre-commit hooks:

1. Install pre-commit hooks:



   ```bash

   uv run pre-commit install

   ```
@@ -76,6 +79,7 @@ class TeddiSource(Protocol): 
### 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
@@ -83,12 +87,14 @@ All requests use `create_cached_teddi_session()`: 
### 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)
@@ -98,14 +104,14 @@ Both expose identical tools: 
### 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

1. Update `SearchRequest` dataclass

1. Update HTTP call in `client.py`

1. Update CLI in `cli.py`

1. Update MCP server in `server.py`

1. Add tests



## 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`.
 
1. **Async-First**: All core methods async. Use `asyncio.run()` for sync wrappers.

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