ASD-STE100 Simplified Technical English
An MCP server for the ASD-STE100 (Simplified Technical English) Issue 9 standard.
Open source Open in the app JSON README (API)
About
An MCP server for the ASD-STE100 (Simplified Technical English) Issue 9 standard.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- dfch
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 3.0.0
- Stars
- 2
- Last push
- 2026-08-02T13:15:00Z
- Repository state
- ativo
- Language
- Python
- License
- AGPL-3.0
- Added
- 2026-08-29 03:02:42
- Updated
- 2026-08-29 03:02:42
- Origin id
io.github.dfch/biz-dfch-asdste100mcp
README
# biz.dfch.AsdSte100Mcp
<!-- mcp-name: io.github.dfch/biz-dfch-asdste100mcp -->
[](https://www.asd-ste100.org/)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://github.com/dfch/biz.dfch.AsdSte100Mcp/actions/workflows/ci.yml)
[](https://test.pypi.org/project/biz-dfch-asdste100mcp/)
[](https://www.pypi.org/project/biz-dfch-asdste100mcp/)
[](https://pypistats.org/packages/biz-dfch-asdste100mcp)
[](https://registry.modelcontextprotocol.io/?q=io.github.dfch/biz-dfch-asdste100mcp)
[](#authentication)
An MCP server for the [ASD-STE100 (Simplified Technical English) Issue 9 standard](https://www.asd-ste100.org/).
ASD-STE100: Copyright by (c) [ASD](https://www.asd-europe.org/).
I am in no way affiliated with ASD. ASD does not endorse my work.
## Table of Contents
- [Tools](#tools)
- [Resources](#resources)
- [Installation](#installation)
- [Usage](#usage)
- [Authentication](#authentication)
- [Add to OpenCode](#add-to-opencode)
- [Development](#development)
- [Related Projects](#related-projects)
- [Make a Release](#make-a-release)
- [License](#license)
## Authentication
This server exposes only read-only lookup tools and resources over
vocabulary and rules data that is bundled with the package; there is
nothing to authenticate against. No API keys, tokens, or credentials are
required or supported in either `stdio` or `sse` transport mode. If you
expose the `sse` transport beyond `localhost`, secure it at the network
layer (e.g. a reverse proxy) rather than expecting the server to
authenticate requests itself.
## Tools
### Vocabulary
| Tool | Description |
|---|---|
| `word_find` | Search for a term by exact name (case-insensitive) in the ASD-STE100 Issue 9 vocabulary. Return approved/rejected status, part of speech, STE examples, and approved alternatives. Use this first when you know the exact word. Use `word_match` with a wildcard if this tool returns no items. |
| `word_find_many` | Search for multiple terms by exact name (case-insensitive) in a single call. Returns one `WordFindEntry` per input term (`term` + `results`), in the same order as the input, each holding 0, 1, or more matching vocabulary entries. |
| `word_match` | Search the vocabulary using a regular expression pattern. Return all entries whose term matches. Use it to find all words with a common prefix or pattern (e.g. ^de or .*tion$). Paginated (`max_results`/`offset`); returns a `WordResult`. |
| `word_fuzzy` | Search for a term with sequence-matching (Python difflib.get_close_matches). Results may not be obvious — use when `word_find` returns nothing and you want fuzzy suggestions. |
| `word_list` | Return all vocabulary entries. Only use when you need to process the full vocabulary. Use `word_count` instead if you only need the total. Paginated (`max_results`/`offset`); returns a `WordResult`. |
| `word_count` | Return the total number of entries in the vocabulary. Use instead of `word_list` when you only need the count. |
| `word_synonym` | Search for vocabulary entries that are WordNet synonyms of a word, via the `biz-dfch-asdste100nlp` library's `Nlp` class. Use this to find approved alternatives for a non-STE word. |
### Rules
| Tool | Description |
|---|---|
| `rules_find` | Search for rules in the ruleset by exact id (case-insensitive), e.g. `R1.1` or `GR-8`. Use this first when you know the exact id. |
| `rules_match` | Search rules using a regular expression matched against the rule `name` and `summary`. |
| `rules_search` | Full-text search across every text a rule carries (section, category, name, summary, and all content blocks: text, notes, examples, technical noun/verb lists). Optionally restrict to specific content types. Paginated (`max_results`/`offset`); returns a `SearchResult`. |
| `rules_by_section` | Search for rules by exact section name (case-insensitive), e.g. `Words`. |
| `rules_by_category` | Search for rules by exact category name (case-insensitive), e.g. `Technical nouns`. |
| `rules_examples` | Return content items across rules, optionally scoped by id/section/category and filtered by content type. Paginated (`max_results`/`offset`); returns a `RulesExamplesResult`. |
| `rules_overview` | Return a lightweight, per-rule overview (id, type, section, category, name, optional summary, and content counts/flags) without shipping every content item. |
| `rules_toc` | Return the distinct (section, category) pairs as a table-of-contents outline, optionally scoped to one section. |
## Resources
Read-only resources let a client browse or attach ruleset data directly (e.g. via
an "@mention" or resource picker), without going through a tool call.
| Resource URI | Description |
|---|---|
| `asdste100://rules/toc` | Table-of-contents outline of the ruleset: the distinct (section, category) pairs, each with the ids they contain. Mirrors the `rules_toc` tool with no `section` filter. |
| `asdste100://rules/rule/{id_}` | A single rule/recommendation/information item by exact id (case-insensitive), e.g. `asdste100://rules/rule/R1.1`. Mirrors the `rules_find` tool; an unknown id resolves to an empty list rather than an error. |
| `asdste100://version` | Installed version numbers of the MCP server itself and its three data-backing libraries: `biz-dfch-asdste100vocab`, `biz-dfch-asdste100rules`, and `biz-dfch-asdste100nlp`. |
## Installation
```bash
pip install biz-dfch-asdste100mcp
```
Or with [uv](https://docs.astral.sh/uv/):
```bash
uv add biz-dfch-asdste100mcp
```
## Usage
### MCP Inspector
If you want to test the MCP server without a tool like `OpenCode`, you can do this with [`MCP Inspector`](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector).
`MCP Inspector` is part of the `mcp[cli]` package. When you install this project with `--extra dev` you can use `MCP Inspector`.
NOTE: The examples below use `bunx` instead of `npx` to launch `MCP Inspector`; `npx` has not been tested.
### stdio (Claude Desktop, OpenCode, and other MCP hosts)
```bash
asdste100-mcp
```
Run `MCP Inspector` against the server over `stdio`:
```bash
bunx @modelcontextprotocol/inspector uv run --frozen --directory . asdste100-mcp
```
NOTE: Sometimes, the MCP Inspector cannot connect to the MCP server via `stdio`. Use the `sse` option (see below) instead.
### SSE / network
```bash
asdste100-mcp --transport sse --host localhost --port 8000
```
NOTE: You do not have to supply the option `--port` to the MCP server. The default value of `port` is `8000`.
Start the server, then connect `MCP Inspector` to it — these are two separate commands, run in two separate terminals:
```bash
# terminal 1: start the server
uvx --from . asdste100-mcp -t sse
```
```bash
# terminal 2: launch the inspector and connect it to the running server
bunx @modelcontextprotocol/inspector
```
### Options
| Option | Env var | Default | Description |
|---|---|---|---|
| `--transport` | `ASDSTE100_MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `sse` |
| `--host` | `ASDSTE100_MCP_HOST` | `localhost` | Bind address (SSE only) |
| `--port` | `ASDSTE100_MCP_PORT` | `8000` | TCP port (SSE only) |
| `--env` | — | auto-discovered | Path to a `.env` file |
| `--file` / `-f` | `ASDSTE100_MCP_FILES` | _(empty)_ | Path to a vocabulary file (`*.jsonl`); repeatable |
| `--rules-file` / `-r` | `ASDSTE100_MCP_RULES_FILES` | _(empty)_ | Path to a rules file (a single JSON array); repeatable |
### Vocabulary configuration
| Env var | Default | Description |
|---|---|---|
| `ASDSTE100_MCP_FILES` | _(empty)_ | Colon-separated paths to additional vocabulary files |
| `ASDSTE100_MCP_USE_STE100` | `true` | Load the built-in ASD-STE100 Issue 9 vocabulary |
| `ASDSTE100_MCP_USE_STE100_TECHNICAL_WORDS` | `false` | Also load the technical words vocabulary |
### Rules configuration
| Env var | Default | Description |
|---|---|---|
| `ASDSTE100_MCP_RULES_FILES` | _(empty)_ | Colon-separated paths to additional rules files (each a single JSON array) |
| `ASDSTE100_MCP_USE_STE100_RULES` | `true` | Load the built-in ASD-STE100 Issue 9 ruleset |
## Add to OpenCode
To add the ASD-STE100 (Simplified Technical English) MCP server to your OpenCode configuration:
1. Open your OpenCode config file (typically `~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`)
2. Add the following configuration to the `mcp` section (and use it via `stdio`):
```json
"asdste100": {
"type": "local",
"enabled": true,
"command": ["uvx", "--from", "biz-dfch-asdste100mcp", "asdste100-mcp"]
}
```
3. Save the file and restart OpenCode
This enables OpenCode to access ASD-STE100 vocabulary and rules lookups for technical writing and documentation compliance.
## Development
### Install dev dependencies
```bash
uv sync --all-extras
```
### Run linters
```bash
uv run --frozen ruff format --check
uv run --frozen ruff check
uv run --frozen pylint $(git ls-files '*.py')
```
### Run tests
```bash
uv run --frozen python -m unittest discover -v -s tests -t . -p "test_*.py"
```
## Related Projects
This server is part of the ASD-STE100 tooling family:
* [biz.dfch.AsdSte100Vocab](https://github.com/dfch/biz.dfch.AsdSte100Vocab) — the ASD-STE100 Issue 9 vocabulary library
* [biz.dfch.AsdSte100Rules](https://github.com/dfch/biz.dfch.AsdSte100Rules) — the ASD-STE100 Issue 9 ruleset library
* [biz.dfch.AsdSte100Nlp](https://github.com/dfch/biz.dfch.AsdSte100Nlp) — WordNet-based synonym lookup for ASD-STE100 words
* [biz.dfch.AsdSte100Lookup](https://github.com/dfch/biz.dfch.AsdSte100Lookup) — an interactive CLI to look up words and rules
* [biz.dfch.AsdSte100Mcp](https://github.com/dfch/biz.dfch.AsdSte100Mcp) — this repo: an MCP server exposing vocabulary and rules lookup tools
## Make a Release
### 1. Make sure all tests pass
Before releasing, make sure the CI pipeline is green on the `dev` branch:
```bash
uv run --frozen ruff format --check
uv run --frozen ruff check
uv run --frozen pylint $(git ls-files '*.py')
uv run --frozen python -m unittest discover -v -s tests -t . -p "test_*.py"
```
### 2. Increase the version
Update the version in `pyproject.toml`:
```toml
version = "x.y.z"
```
### 3. Commit and push to `dev`
```bash
git add pyproject.toml CHANGELOG.md
git commit -m "chore: bump version to vx.y.z"
git push origin dev
```
### 4. Merge `dev` into `main`
```bash
git checkout main
git merge dev
git push origin main
```
### 5. Create and push a version tag
```bash
export VERSION=x.y.z
git tag v${VERSION}
git push origin v${VERSION}
```
Pushing the tag triggers the `publish.yml` workflow, which will:
1. Build the sdist and wheel.
2. Publish to **TestPyPI** (environment `testpypi`).
3. Publish to **PyPI** (environment `pypi`), only if TestPyPI succeeded.
4. Publish to the **MCP Registry** (`publish-to-mcp-registry` job) — requires the new version to be live on PyPI first.
5. Create a **GitHub Release** with auto-generated notes and the distribution artifacts attached.
Then switch back to `dev` to continue work:
```bash
git checkout dev
```
### Configure Trusted Publishing
The workflow uses OIDC Trusted Publishing — no API tokens or secrets are needed.
#### GitHub: create environments
Go to your repo → **Settings** → **Environments** and create two environments:
| Environment | Recommended protection |
|---|---|
| `testpypi` | None required |
| `pypi` | Add a required reviewer to prevent accidental production releases |
#### TestPyPI
Log in at [test.pypi.org](https://test.pypi.org) → **Your account** → **Publishing** → **Add a new pending publisher**:
| Field | Value |
|---|---|
| PyPI project name | `biz-dfch-asdste100mcp` |
| Owner | `dfch` |
| Repository | `biz.dfch.AsdSte100Mcp` |
| Workflow name | `publish.yml` |
| Environment | `testpypi` |
#### PyPI
Log in at [pypi.org](https://pypi.org) → **Your account** → **Publishing** → **Add a new pending publisher**:
| Field | Value |
|---|---|
| PyPI project name | `biz-dfch-asdste100mcp` |
| Owner | `dfch` |
| Repository | `biz.dfch.AsdSte100Mcp` |
| Workflow name | `publish.yml` |
| Environment | `pypi` |
### MCP Registry Publishing
The `publish-to-mcp-registry` job uses GitHub OIDC authentication and does not require additional setup — it will automatically publish to the [official MCP Registry](https://registry.modelcontextprotocol.io/) once the package is live on PyPI.
Verify your server is registered:
```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.dfch/biz-dfch-asdste100mcp"
```
## License
[AGPL-3.0-or-later](LICENSE)