Skip to main content
Glama
woowoeth

ourword-mcp

by woowoeth
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

ourword-mcp

403 deep reads on 171 figures and classics across 2,600 years, indexed by the situation you're actually in. An MCP server with no search — the client's model does the matching.

Why there is no search in here

Someone says: "my boss keeps changing priorities."

The entry in the library that answers it reads: "Five things are on fire and I am spread across all five."

Those two sentences share zero words. Keyword search cannot get from one to the other; the model calling this server can, instantly. So the server stopped trying. It exposes the index in two levels and lets the model pick:

browse()                              → 121 situation groups
browse(group="Everything is urgent…") → the specific wordings, each with chapters
read_chapter(url)                     → full text

That design is not a preference. The first version was a literal search: on real situation sentences it returned 0 hits, top score 0.11. The scoring function had its denominator rewritten twice before the conclusion became obvious — nothing belonged in that position at all.

search() still exists as a fallback for when the model cannot pick. It is documented as a fallback, in the tool description the model reads.

Related MCP server: EPUB Reader MCP Server

Install

claude mcp add ourword -- uvx ourword-mcp

Before that lands on PyPI, straight from the repo — same one line:

claude mcp add ourword -- uvx --from git+https://github.com/woowoeth/ourword-mcp ourword-mcp

Or from source, no packaging involved — it is one file and the standard library:

claude mcp add ourword -- python3 /path/to/ourword_mcp.py

Nothing to clone: the index is fetched from the web and cached locally for a day.

The three tools

tool

what it does

browse(lang, group)

no group: list the situation groups. With group: the specific wordings under it, each with the chapters that answer it.

read_chapter(url)

full text of one chapter. Use the url browse gave you.

search(query, limit)

literal fallback. Prefer browse.

lang is zh (default) or en.

Chinese and English are not translations of each other

The same 403 chapters, entered through a different set of doors: 112 situation groups / 655 wordings in Chinese, 121 / 629 in English. What an English speaker says to themselves at 2am is not a translation of what a Chinese speaker says — so the two indexes grew separately. The Chinese side has situations about social-insurance gaps and the graduate exam; the English side has its own.

What it will not do

Written into the tool descriptions, because that is what the model reads:

  • Only what is in the library. Nothing matches → say so. Do not invent.

  • Every item carries a URL. An answer that cannot point back to the source does not get written.

  • Not personal medical, legal or financial advice. How people before you thought about such questions, yes. What you should do, no.

Ask it about a cat losing fur and it returns found: 0 and tells the model, in so many words, not to make something up.

Also available as an Agent Skill

tools/skill/ourword-en/ in the repo — for clients without MCP. It reads the same index over plain HTTP (https://ourword.ai/en/llms.txt), so it works with no configuration at all. MCP is for people who can wire up a server; the Skill is for everyone else.

Privacy

No telemetry. The server fetches two public JSON files and caches them in ~/.cache/ourword-mcp. Install counts come from public CDN and PyPI numbers, not from anything this program reports.

MIT. Source: https://github.com/woowoeth/woowoeth.github.io/tree/main/tools/mcp

Available Tools

3 tools
browseA

主入口。 不带参数：列出库里覆盖的全部处境归类（一百多组）。带 group：列出那一组下面的具体说法，以及每条对应的「以前的人怎么处理」。用法是你先读归类、按语义挑最像用户此刻的那一组 —— 字面往往对不上（用户说「领导总改优先级」，库里那条是「全都重要，我砍哪个都疼」）。只返回库里真有的内容；检索不到就说没有，不要编。每条都带 URL，答案要能指回原文。这里给的是「以前的人在同一处境里怎么处理」，不是医疗、法律或金融的个人建议。

ParametersJSON Schema
NameRequiredDescriptionDefault
langNo库的语言：zh 中文站，en 英文站。用户说英文就传 en —— 两边的处境不是互译，是各自长出来的（中文有社保、考研，英文另有别的）。zh
groupNo处境归类，从不带参数的那次结果里挑

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

无注解，描述承担全部责任。明确披露只返回库中真实内容、不编造、每条带 URL、内容为历史处理而非个人建议。行为透明性良好，但未提及结果数量或分页等潜在限制。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

开头用「主入口」点明核心用途，随后分层说明无参数和带参数行为，最后补充使用方法和注意事项。结构清晰，但篇幅略长，部分信息（如历史处理免责声明）可简化。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

工具简单（2 参数，无输出 schema），描述覆盖了调用方式、参数选择逻辑、返回内容特征和边界情况。唯一缺失是返回格式的详细说明（如条目结构），但描述已暗示包含说法和 URL，基本完整。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema 覆盖率 100%，描述补充了 lang 参数的语义（中英文站内容不同、非互译），以及 group 参数需从无参数结果中选取。这些补充超越了 schema 本身，有助于 agent 正确使用。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

明确说明是主入口，无参数列出全部归类，带 group 列出具体说法和历史处理。动词+资源+行为都很具体，与 read_chapter 和 search 区分明显。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

给出了明确的使用流程：先读归类、按语义挑选最匹配的组，并举例说明字面匹配可能失败。还说明了检索不到时的处理方式。但未明确提及与 search 或 read_chapter 的替代关系，略欠完整。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_chapterA

取某一篇的完整正文。url 用 browse / search 返回的那个，不要自己拼。

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
langNo库的语言：zh 中文站，en 英文站。用户说英文就传 en —— 两边的处境不是互译，是各自长出来的（中文有社保、考研，英文另有别的）。zh

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for behavioral disclosure. It adds a meaningful behavioral constraint: the URL must come from browse/search and must not be hand-crafted. However, it does not disclose other traits such as failure behavior, output shape, or any limitations, so it is only partially transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The core purpose is front-loaded, followed immediately by the critical usage constraint. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with two parameters and no output schema, the description covers the essential operational context: what to pass and where it comes from. It is slightly incomplete in not mentioning any edge behavior or return format, but the simplicity of the tool and the schema's coverage of lang reduce the impact of that gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema coverage is 50%: only lang is described in the schema, while url has no description. The tool description compensates for the url gap by explaining exactly where the url should come from ('url 用 browse / search 返回的那个，不要自己拼'), which adds essential semantics. The lang parameter already has a thorough schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: '取某一篇的完整正文' (retrieve the full body text of a specific piece). It also differentiates from sibling tools browse and search by implying that browse/search are used to find the URL, while read_chapter fetches the full content for that URL.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear context signal: use the URL returned by browse or search, and do not construct one yourself. This effectively routes the agent to the correct workflow. It does not explicitly state when not to use the tool, but the instruction is unambiguous enough for the intended use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.2.0
    • First observedbrowse
    • First observedread_chapter
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct role: browse navigates by semantic category, search is an explicit literal fallback for when browse fails, and read_chapter retrieves full text by URL. The descriptions even specify usage order, so an agent is unlikely to misselect.

Naming Consistency4/5

All names are lowercase imperative verbs and clearly indicate actions. The only minor inconsistency is that read_chapter follows a verb_noun pattern while browse and search are bare verbs, but this is readable and does not create confusion.

Tool Count5/5

Three tools is well-scoped for this focused read-only reference server. Each tool earns its place: semantic browsing, literal search fallback, and full-text retrieval cover the essential workflow without unnecessary bloat.

Completeness5/5

The server's stated purpose is retrieving curated situational wisdom, and the tools cover the complete read-only journey: list/select categories, inspect entries, retrieve full chapters, and fall back to literal search. No create/update/delete operations are expected for this domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers