Commit 674f8208 authored by Jan Reimes's avatar Jan Reimes
Browse files

feat(skills): add MCP and CLI usage documentation for TEDDI tools 

- Introduce `@mcp-teddi` skill for MCP usage and querying terms.
- Add `@cli-teddi` skill for CLI operations with TEDDI.
- Provide detailed command usage and troubleshooting guidance.
parent 879ba086

.agents/skills/README.md

+8 −0
Original line number Diff line number Diff line
@@ -39,6 +39,14 @@ Change Request procedure, workflow, status tracking, and CR database. 
- [SKILL.md](3gpp-change-request/SKILL.md) - Full CR reference

- [workflow.md](3gpp-change-request/workflow.md) - Quick workflow guide



### @mcp-teddi



MCP usage for TEDDI term and definition search from Copilot chat tools.



### @cli-teddi



CLI usage for teddi-mcp via `uv run` for search, technical body listing, and server mode.



## Cross-Reference Map



| From \\ To | basics | working-groups | meetings | tdocs | portal-auth | releases | specs | change-request |

.agents/skills/cli-teddi/SKILL.md

0 → 100644
+77 −0
Original line number Diff line number Diff line 
---

name: cli-teddi

description: CLI usage for teddi-mcp from source in this repository. Use when running TEDDI term searches, listing technical bodies, or starting the TEDDI MCP server from terminal with uv run commands.

---



# CLI: teddi-mcp



## Overview



Use the teddi CLI for scripted or terminal-based TEDDI operations:



- search terms and definitions,

- list available technical bodies,

- start the MCP server over stdio.



Always run through uv.



## Commands



### Search a term



```bash

uv run --directory src/teddi-mcp teddi-mcp search term HATS

```



### Search with filters



```bash

uv run --directory src/teddi-mcp teddi-mcp search term HATS \

  --search-in both \

  --search-pattern exactmatch \

  --technical-bodies 3gpp,itu,stq

```



### List technical bodies



```bash

uv run --directory src/teddi-mcp teddi-mcp search list-bodies

```



### Machine-readable output



```bash

uv run --directory src/teddi-mcp teddi-mcp search term HATS --output json

uv run --directory src/teddi-mcp teddi-mcp search term HATS --output ison

uv run --directory src/teddi-mcp teddi-mcp search term HATS --output toon

```



### Run server mode



```bash

uv run --directory src/teddi-mcp -m teddi_mcp

```



## Arguments Reference



- `--search-in`: `abbreviations`, `definitions`, `both`

- `--search-pattern`: `exactmatch`, `startingwith`, `endingwith`, `alloccurrences`

- `--technical-bodies`: comma-separated codes such as `3gpp,stq`

- `--output`: `table`, `json`, `ison`, `toon`



## Troubleshooting



If a technical body is reported unknown:



1. Run `search list-bodies` and use returned codes exactly.

2. Retry with normalized lowercase codes.



If exact match returns no rows:



1. Retry using uppercase term.

2. Retry with `--search-pattern alloccurrences`.



If server tools do not refresh after code changes:



1. Reload VS Code window.

2. Re-run the configured MCP command from `.vscode/mcp.json`.

.agents/skills/mcp-teddi/SKILL.md

0 → 100644
+77 −0
Original line number Diff line number Diff line 
---

name: mcp-teddi

description: MCP usage for ETSI TEDDI (Terms and Definitions Database Interactive) through the teddi-mcp server. Use when querying terms/abbreviations, listing technical bodies, validating technical body codes, or retrieving exact term definitions from Copilot chat tools.

---



# MCP Server: TEDDI



## Overview



TEDDI (Terms and Definitions Database Interactive) contains definitions and abbreviations extracted from publicly available ETSI deliverables.



Important behavior:



- The same term can have multiple definitions.

- Differences can be minor spelling variants or technical-body specific meanings.

- Technical body filters can change results significantly.



## Tooling



Use these teddi MCP tools:



- `mcp_teddi-mcp_search_teddi`

- `mcp_teddi-mcp_get_term_info`

- `mcp_teddi-mcp_list_technical_bodies`



## Recommended Workflow



1. Validate or discover technical body codes first with `list_technical_bodies`.

2. Run `search_teddi` with explicit `search_in` and `search_pattern`.

3. Apply `technical_bodies` filtering only with known valid codes.

4. If the user wants one specific entry, use `get_term_info` for exact lookup.

5. Summarize results with:

   - concise definition,

   - body-specific differences,

   - document references (spec + URL) when available.



## Query Patterns



### General term exploration



Use `search_teddi` with:



- `search_in="both"`

- `search_pattern="exactmatch"` for strict matching

- `search_pattern="alloccurrences"` when exact match returns nothing



### Technical-body constrained search



Use comma-separated body codes, for example:



- `technical_bodies="3gpp,stq"`

- `technical_bodies="etsi,itu"`



If a code is rejected, call `list_technical_bodies` and retry with valid codes.



## Interpretation Guidance



When multiple results are returned:



- Do not collapse distinct definitions into one if wording or scope differs.

- Highlight whether definitions are singular/plural variants (for example, "Simulator" vs "Simulators").

- Mention when a requested body has no match.



When no results are returned:



- Retry with different casing (`HATS` vs `hats`).

- Retry with `alloccurrences`.

- Keep the same technical body filter unless the user asks to broaden scope.



## Output Quality



For explanations, include:



1. A one-line plain-language meaning.

2. Context of use (for example, telecom testing, standards terminology).

3. Differences by technical body.

4. Optional references to source specs from TEDDI response data.