ASD-STE100 Simplified Technical English

biz.dfch.AsdSte100Mcp

一个用于 ASD-STE100（简化技术英语）Issue 9 标准的 MCP 服务。

ASD-STE100：版权归 (c) ASD 所有。

我与 ASD 毫无关联。ASD 不为我的作品背书。

目录

• 工具
• 资源
• 安装
• 用法
• 身份验证
• 添加到 OpenCode
• 开发
• 相关项目
• 发布版本
• 许可证

身份验证

此服务仅通过词汇和规则数据提供只读查询工具和资源；这些数据随软件包一同提供，因此无需进行身份验证。无论使用 stdio 还是 sse 传输模式，均无需也不支持 API 密钥、令牌或凭据。如果将 sse 传输暴露到 localhost 之外，请在网络层（例如，通过反向代理）进行保护，而不要指望服务自行验证请求。

工具

词汇

工具	描述
word_find	在 ASD-STE100 Issue 9 词汇表中按确切名称（不区分大小写）搜索术语。返回批准/拒绝状态、词性、STE 示例和批准的替代词。已知确切词语时，请先使用此工具。如果此工具没有返回条目，请使用带通配符的 word_match。
word_find_many	在一次调用中按确切名称（不区分大小写）搜索多个术语。每个输入术语返回一个 WordFindEntry（term + results），顺序与输入相同，每个条目包含 0 个、1 个或多个匹配的词汇项。
word_match	使用正则表达式模式搜索词汇表。返回所有术语匹配的条目。可用于查找具有相同前缀或模式的所有词语（例如 ^de 或 .*tion$）。支持分页（max_results/offset）；返回 WordResult。
word_fuzzy	使用序列匹配（Python difflib.get_close_matches）搜索术语。结果可能不明显——当 word_find 没有返回结果且你需要模糊匹配建议时使用。
word_list	返回所有词汇条目。仅在需要处理完整词汇表时使用。如果只需要总数，请改用 word_count。支持分页（max_results/offset）；返回 WordResult。
word_count	返回词汇条目的总数。只需要计数时，请用此工具代替 word_list。
word_synonym	通过 biz-dfch-asdste100nlp 库的 Nlp 类，搜索某个词的 WordNet 同义词对应的词汇条目。可用于查找非 STE 词语的批准替代词。

规则

工具	描述
rules_find	按确切 ID（不区分大小写）搜索规则集中的规则，例如 R1.1 或 GR-8。已知确切 ID 时，请先使用此工具。
rules_match	使用正则表达式搜索规则，匹配规则的 name 和 summary。
rules_search	对规则包含的所有文本（章节、类别、名称、摘要以及所有内容块：文本、注释、示例、技术名词/动词列表）进行全文搜索。可选择限制内容类型。支持分页（max_results/offset）；返回 SearchResult。
rules_by_section	按确切章节名称（不区分大小写）搜索规则，例如 Words。
rules_by_category	按确切类别名称（不区分大小写）搜索规则，例如 Technical nouns。
rules_examples	返回规则中的内容项，可选择按 ID/章节/类别限定范围，并按内容类型筛选。支持分页（max_results/offset）；返回 RulesExamplesResult。
rules_overview	返回每条规则的精简概览（ID、类型、章节、类别、名称、可选摘要以及内容数量/标记），而不提供所有内容项。
rules_toc	以目录大纲的形式返回不同的（章节、类别）组合，可选择限定在某个章节内。

资源

只读资源让客户端可以直接浏览或附加规则集数据（例如通过 “@提及”或资源选择器），而无需调用工具。

资源 URI	描述
asdste100://rules/toc	规则集的目录大纲：不同的（章节、类别）组合及其包含的 ID。对应于未设置 section 筛选条件的 rules_toc 工具。
asdste100://rules/rule/{id_}	按确切 ID（不区分大小写）返回一条规则/建议/信息项，例如 asdste100://rules/rule/R1.1。对应于 rules_find 工具；未知 ID 会解析为空列表，而不是报错。
asdste100://version	MCP 服务本身及其三个数据后端库的已安装版本号：biz-dfch-asdste100vocab、biz-dfch-asdste100rules 和 biz-dfch-asdste100nlp。

安装

pip install biz-dfch-asdste100mcp

或使用 uv：

uv add biz-dfch-asdste100mcp

使用

MCP Inspector

如果你想在不使用 OpenCode 等工具的情况下测试 MCP 服务，可以使用 MCP Inspector。

MCP Inspector 是 mcp[cli] 软件包的一部分。使用 --extra dev 安装此项目后，即可使用 MCP Inspector。

注意：以下示例使用 bunx 而不是 npx 启动 MCP Inspector；npx 尚未经过测试。

stdio（Claude Desktop、OpenCode 和其他 MCP 宿主）

asdste100-mcp

通过 stdio 对 MCP 服务运行 MCP Inspector：

bunx @modelcontextprotocol/inspector uv run --frozen --directory . asdste100-mcp

注意：有时，MCP Inspector 无法通过 stdio 连接到 MCP 服务。请改用 sse 选项（见下文）。

SSE / 网络

asdste100-mcp --transport sse --host localhost --port 8000

注意：无需向 MCP 服务提供 --port 选项。port 的默认值为 8000。

启动服务，然后将 MCP Inspector 连接到该服务——这是两条独立的命令，需在两个单独的终端中运行：

# terminal 1: start the server
uvx --from . asdste100-mcp -t sse

# terminal 2: launch the inspector and connect it to the running server
bunx @modelcontextprotocol/inspector

选项

选项	环境变量	默认值	描述
--transport	ASDSTE100_MCP_TRANSPORT	stdio	传输模式：stdio 或 sse
--host	ASDSTE100_MCP_HOST	localhost	绑定地址（仅限 SSE）
--port	ASDSTE100_MCP_PORT	8000	TCP 端口（仅限 SSE）
--env	—	自动发现	.env 文件的路径
--file / -f	ASDSTE100_MCP_FILES	(空)	词汇文件（*.jsonl）的路径；可重复指定
--rules-file / -r	ASDSTE100_MCP_RULES_FILES	(空)	规则文件（单个 JSON 数组）的路径；可重复指定

词汇配置

环境变量	默认值	描述
ASDSTE100_MCP_FILES	(空)	其他词汇文件的路径，以冒号分隔
ASDSTE100_MCP_USE_STE100	true	加载内置的 ASD-STE100 Issue 9 词汇
ASDSTE100_MCP_USE_STE100_TECHNICAL_WORDS	false	同时加载技术词汇

规则配置

环境变量	默认值	描述
ASDSTE100_MCP_RULES_FILES	(空)	其他规则文件的路径（每个文件都是单个 JSON 数组），以冒号分隔
ASDSTE100_MCP_USE_STE100_RULES	true	加载内置的 ASD-STE100 Issue 9 规则集

添加到 OpenCode

将 ASD-STE100（简明技术英语）MCP 服务添加到 OpenCode 配置中：

1. 打开 OpenCode 配置文件（通常为 ~/.config/opencode/opencode.json 或 ~/.config/opencode/opencode.jsonc）

2. 将以下配置添加到 mcp 部分（并通过 stdio 使用）：

"asdste100": {
  "type": "local",
  "enabled": true,
  "command": ["uvx", "--from", "biz-dfch-asdste100mcp", "asdste100-mcp"]
}

3. 保存文件并重启 OpenCode

这样，OpenCode 就可以访问 ASD-STE100 词汇和规则查询功能，用于技术写作和文档合规性检查。

开发

安装开发依赖

uv sync --all-extras

运行代码检查工具

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"

相关项目

此服务属于 ASD-STE100 工具系列：

• biz.dfch.AsdSte100Vocab — ASD-STE100 Issue 9 词汇库
• biz.dfch.AsdSte100Rules — ASD-STE100 Issue 9 规则集库
• biz.dfch.AsdSte100Nlp — 基于 WordNet 的 ASD-STE100 词汇同义词查询
• biz.dfch.AsdSte100Lookup — 用于查询单词和规则的交互式命令行工具
• biz.dfch.AsdSte100Mcp — 本仓库：提供词汇和规则查询工具的 MCP 服务

发布版本

1. 确保所有测试均通过

发布前，确保 dev 分支上的 CI 流水线通过：

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. 提高版本号

更新 pyproject.toml 中的版本号：

version = "x.y.z"

3. 提交并推送到 dev

git add pyproject.toml CHANGELOG.md
git commit -m "chore: bump version to vx.y.z"
git push origin dev

4. 将 dev 合并到 main

git checkout main
git merge dev
git push origin main

5. 创建并推送版本标签

export VERSION=x.y.z
git tag v${VERSION}
git push origin v${VERSION}

推送标签会触发 publish.yml 工作流，该工作流将：

1. 构建 sdist 和 wheel。
2. 发布到 TestPyPI（环境 testpypi）。
3. 发布到 PyPI（环境 pypi），仅当 TestPyPI 发布成功时才会执行。
4. 发布到 MCP Registry（publish-to-mcp-registry 任务）——要求新版本先在 PyPI 上发布。
5. 创建一个 GitHub Release，附带自动生成的说明和发行包文件。

然后切回 dev 继续工作：

git checkout dev

配置可信发布

该工作流使用 OIDC 可信发布——无需 API 令牌或密钥。

GitHub：创建环境

前往仓库 → Settings → Environments，并创建两个环境：

环境	推荐的保护措施
testpypi	无需配置
pypi	添加必需的审核者，以防意外发布到生产环境

TestPyPI

登录 test.pypi.org → Your account → Publishing → Add a new pending publisher：

字段	值
PyPI 项目名称	biz-dfch-asdste100mcp
所有者	dfch
仓库	biz.dfch.AsdSte100Mcp
工作流名称	publish.yml
环境	testpypi

PyPI

登录 pypi.org → Your account → Publishing → Add a new pending publisher：

字段	值
PyPI 项目名称	biz-dfch-asdste100mcp
所有者	dfch
仓库	biz.dfch.AsdSte100Mcp
工作流名称	publish.yml
环境	pypi

发布到 MCP Registry

publish-to-mcp-registry 任务使用 GitHub OIDC 身份验证，无需额外设置——软件包在 PyPI 上发布后，它会自动发布到官方 MCP Registry。

验证你的服务是否已注册：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.dfch/biz-dfch-asdste100mcp"

许可证

AGPL-3.0-or-later