mcp-reqcheck 0.1.0__tar.gz

mcp_reqcheck-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.3
+Name: mcp-reqcheck
+Version: 0.1.0
+Summary: MCP server for reqCheck
+Author: Hongjin Chen
+Author-email: Hongjin Chen <188007812+hjchen114514@users.noreply.github.com>
+Requires-Dist: mcp[cli]>=2.1.1
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# ReqCheck MCP server
+
+Finds ambiguous terms in a requirements document, checked against
+**ISO/IEC/IEEE 29148:2018**, and hands the client the question templates needed
+to ask the author what they actually meant.
+
+Detection is deterministic — regex over a versioned rule catalog, no model
+involved — so the same text always produces the same findings, and every
+finding cites the clause it came from.
+
+Part of [ReqCheck](https://github.com/hjchen114514/ReqCheck), which also ships a
+web app for the same checks.
+
+## What it exposes
+
+| Kind | Name | Purpose |
+|---|---|---|
+| Tool | `ambiguity_analysis(text)` | Every flagged term with its statement, severity, explanation, ISO citation, and question templates |
+| Resource | `reqcheck://knowledge-base` | The full rule catalog as authored, with citations |
+| Prompt | `check_requirements(text)` | Analyses a document and reports findings in a fixed format |
+
+## Install from PyPI
+
+Once published, nothing needs cloning.
+
+**Claude Code:**
+
+```bash
+claude mcp add reqcheck -- uvx mcp-reqcheck
+```
+
+**Claude Desktop** — add to
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ReqCheck": { "command": "uvx", "args": ["mcp-reqcheck"] }
+  }
+}
+```
+
+Then restart Desktop.
+
+## Install from source
+
+**1. Install uv** (skip if you already have it):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**2. Get the code:**
+
+```bash
+git clone https://github.com/hjchen114514/ReqCheck.git
+cd ReqCheck/apps/mcp_reqCheck
+```
+
+**3a. Claude Desktop:**
+
+```bash
+uv run mcp install src/mcp_reqcheck/server.py --with PyYAML
+```
+
+Restart Desktop. `ReqCheck` should show green under Settings → Developer.
+
+**3b. Claude Code** — needs the absolute path. Print it from this folder:
+
+```bash
+pwd
+# /Users/you/ReqCheck/apps/mcp_reqCheck
+```
+
+```bash
+claude mcp add reqcheck -- uv run --with "mcp[cli]" --with PyYAML mcp run <paste-path>/src/mcp_reqcheck/server.py
+```
+
+Check it with `claude mcp list`.
+
+> **`--with PyYAML` is required when running from source.** The client launches
+> the server from its own working directory, so uv never reads this project's
+> `pyproject.toml` and builds an environment from the `--with` flags alone.
+> Without it the catalog loader fails on `import yaml` and the client reports
+> "Server disconnected". Installed users don't need it — `uvx` resolves
+> declared dependencies.
+
+## Use it
+
+Ask your client something like:
+
+> Check these requirements for ambiguity:
+> The system shall be user-friendly and load significantly faster than the old site.
+
+It calls `ambiguity_analysis`, gets back the flagged terms with their reasons
+and citations, and asks you follow-up questions rather than rewriting your
+requirement for you.
+
+## Develop
+
+```bash
+uv run mcp dev src/mcp_reqcheck/server.py
+```
+
+Opens the MCP Inspector, where you can call the tool, read the resource, and
+render the prompt without a client.
+
+### Layout
+
+`server.py` holds the records, the rule catalog, the analyser, and the MCP
+surface in one module, with `ambiguity_rules.yaml` beside it. That is
+deliberate: a client may load the file directly (`mcp run server.py`, with no
+package around it) or run the installed console script (`uvx mcp-reqcheck`,
+with one), and imports between sibling files resolve differently in those two
+cases. Importing nothing of its own makes both behave identically.
+
+Two details in that file must stay as they are, or the file-based launch
+breaks:
+
+- **no `from __future__ import annotations`** — it turns annotations into
+  strings, which `dataclasses` resolves through `sys.modules[cls.__module__]`,
+  and that is `None` for a directly-loaded file
+- **`Pattern[str]`, not `re.Pattern[str]`** — same reason
+
+The catalog and analyser are copied from `apps/api`. Rule changes made there
+need copying here too.
+
+## Publishing
+```bash
+uv build
+uv publish --index testpypi     # sandbox first
+uv publish                      # then the real index
+```

mcp_reqcheck-0.1.0/README.md

@@ -0,0 +1,133 @@
+# ReqCheck MCP server
+
+Finds ambiguous terms in a requirements document, checked against
+**ISO/IEC/IEEE 29148:2018**, and hands the client the question templates needed
+to ask the author what they actually meant.
+
+Detection is deterministic — regex over a versioned rule catalog, no model
+involved — so the same text always produces the same findings, and every
+finding cites the clause it came from.
+
+Part of [ReqCheck](https://github.com/hjchen114514/ReqCheck), which also ships a
+web app for the same checks.
+
+## What it exposes
+
+| Kind | Name | Purpose |
+|---|---|---|
+| Tool | `ambiguity_analysis(text)` | Every flagged term with its statement, severity, explanation, ISO citation, and question templates |
+| Resource | `reqcheck://knowledge-base` | The full rule catalog as authored, with citations |
+| Prompt | `check_requirements(text)` | Analyses a document and reports findings in a fixed format |
+
+## Install from PyPI
+
+Once published, nothing needs cloning.
+
+**Claude Code:**
+
+```bash
+claude mcp add reqcheck -- uvx mcp-reqcheck
+```
+
+**Claude Desktop** — add to
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ReqCheck": { "command": "uvx", "args": ["mcp-reqcheck"] }
+  }
+}
+```
+
+Then restart Desktop.
+
+## Install from source
+
+**1. Install uv** (skip if you already have it):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**2. Get the code:**
+
+```bash
+git clone https://github.com/hjchen114514/ReqCheck.git
+cd ReqCheck/apps/mcp_reqCheck
+```
+
+**3a. Claude Desktop:**
+
+```bash
+uv run mcp install src/mcp_reqcheck/server.py --with PyYAML
+```
+
+Restart Desktop. `ReqCheck` should show green under Settings → Developer.
+
+**3b. Claude Code** — needs the absolute path. Print it from this folder:
+
+```bash
+pwd
+# /Users/you/ReqCheck/apps/mcp_reqCheck
+```
+
+```bash
+claude mcp add reqcheck -- uv run --with "mcp[cli]" --with PyYAML mcp run <paste-path>/src/mcp_reqcheck/server.py
+```
+
+Check it with `claude mcp list`.
+
+> **`--with PyYAML` is required when running from source.** The client launches
+> the server from its own working directory, so uv never reads this project's
+> `pyproject.toml` and builds an environment from the `--with` flags alone.
+> Without it the catalog loader fails on `import yaml` and the client reports
+> "Server disconnected". Installed users don't need it — `uvx` resolves
+> declared dependencies.
+
+## Use it
+
+Ask your client something like:
+
+> Check these requirements for ambiguity:
+> The system shall be user-friendly and load significantly faster than the old site.
+
+It calls `ambiguity_analysis`, gets back the flagged terms with their reasons
+and citations, and asks you follow-up questions rather than rewriting your
+requirement for you.
+
+## Develop
+
+```bash
+uv run mcp dev src/mcp_reqcheck/server.py
+```
+
+Opens the MCP Inspector, where you can call the tool, read the resource, and
+render the prompt without a client.
+
+### Layout
+
+`server.py` holds the records, the rule catalog, the analyser, and the MCP
+surface in one module, with `ambiguity_rules.yaml` beside it. That is
+deliberate: a client may load the file directly (`mcp run server.py`, with no
+package around it) or run the installed console script (`uvx mcp-reqcheck`,
+with one), and imports between sibling files resolve differently in those two
+cases. Importing nothing of its own makes both behave identically.
+
+Two details in that file must stay as they are, or the file-based launch
+breaks:
+
+- **no `from __future__ import annotations`** — it turns annotations into
+  strings, which `dataclasses` resolves through `sys.modules[cls.__module__]`,
+  and that is `None` for a directly-loaded file
+- **`Pattern[str]`, not `re.Pattern[str]`** — same reason
+
+The catalog and analyser are copied from `apps/api`. Rule changes made there
+need copying here too.
+
+## Publishing
+```bash
+uv build
+uv publish --index testpypi     # sandbox first
+uv publish                      # then the real index
+```

mcp_reqcheck-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "mcp-reqcheck"
+version = "0.1.0"
+description = "MCP server for reqCheck"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "mcp[cli]>=2.1.1",
+    "PyYAML>=6.0",
+]
+
+[[project.authors]]
+name = "Hongjin Chen"
+email = "188007812+hjchen114514@users.noreply.github.com"
+
+[project.scripts]
+mcp-reqcheck = "mcp_reqcheck:main"
+
+[build-system]
+requires = ["uv_build>=0.12.6,<0.13.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

mcp_reqcheck-0.1.0/pyproject.toml.orig

@@ -0,0 +1,27 @@
+[project]
+name = "mcp-reqcheck"
+version = "0.1.0"
+description = "MCP server for reqCheck"
+readme = "README.md"
+authors = [
+    { name = "Hongjin Chen", email = "188007812+hjchen114514@users.noreply.github.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "mcp[cli]>=2.1.1",
+    # The rule catalog ships as ambiguity_rules.yaml beside server.py.
+    "PyYAML>=6.0",
+]
+
+[project.scripts]
+mcp-reqcheck = "mcp_reqcheck:main"
+
+[build-system]
+requires = ["uv_build>=0.12.6,<0.13.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name= "testpypi"
+url="https://test.pypi.org/simple/"
+publish-url="https://test.pypi.org/legacy/"
+explicit=true

mcp_reqcheck-0.1.0/src/mcp_reqcheck/__init__.py

@@ -0,0 +1,17 @@
+"""ReqCheck MCP server package."""
+
+
+def main() -> None:
+    """Console-script entry point. `uvx mcp-reqcheck` lands here.
+
+    The import is deferred so that `import mcp_reqcheck` on its own does not
+    build the server. server.py imports back through this package, and a
+    module-level import here would load and initialise it twice, compiling the
+    rule catalog once per copy.
+    """
+    from mcp_reqcheck.server import mcp
+
+    mcp.run()
+
+
+__all__ = ["main"]

mcp_reqcheck-0.1.0/src/mcp_reqcheck/ambiguity_rules.yaml

@@ -0,0 +1,237 @@
+# ReqCheck ambiguity knowledge base
+#
+# Every rule below is derived from ISO/IEC/IEEE 29148:2018 (see sources.md).
+# Rules are team-authored paraphrases with citations, not copied standard text.
+#
+# Detection is purely deterministic: C3 AmbiguityAnalyzer matches these
+# phrases with word boundaries and computes exact character offsets.
+# No AI is involved in detection.
+#
+# Severity guide:
+#   high   - the requirement almost certainly cannot be verified as written
+#   medium - the requirement is likely to be read two different ways
+#   low    - worth a look, but frequently acceptable in context
+
+catalog_version: "1.0.0"
+
+sources:
+  ISO29148:
+    title: "ISO/IEC/IEEE 29148:2018 - Systems and software engineering - Life cycle processes - Requirements engineering"
+    short_name: "ISO/IEC/IEEE 29148:2018"
+    clause: "p.22 (well-formed requirements, unbounded and ambiguous terms); p.12 (Unambiguous)"
+    url: "https://www.iso.org/standard/72089.html"
+
+rules:
+  # --- p.22: "superlatives (such as 'best', 'most')" -----------------------
+  - id: AMB-SUPER-001
+    phrases:
+      ["best", "worst", "most", "least", "optimal", "optimum",
+       "state of the art", "state-of-the-art", "cutting edge", "world class"]
+    category: superlative
+    category_label: "Superlative"
+    severity: high
+    explanation: >-
+      Superlatives assert an extreme without naming a baseline or a way to
+      measure it, so no test can confirm the requirement was met.
+    question_templates:
+      - "Compared with what baseline is this the best or the most? Name the alternative."
+      - "What measurable value would demonstrate this extreme was achieved?"
+    source: ISO29148
+
+  # --- p.22: "subjective language (such as 'user friendly', 'easy to use',
+  #            'cost effective')" ----------------------------------------
+  - id: AMB-SUBJ-001
+    phrases:
+      ["user friendly", "user-friendly", "easy to use", "easy", "simple to use",
+       "cost effective", "cost-effective", "efficient", "efficiently", "robust",
+       "flexible", "seamless", "seamlessly", "intuitive", "convenient",
+       "user experience", "modern", "clean", "nice", "good", "powerful"]
+    category: subjective_language
+    category_label: "Subjective language"
+    severity: high
+    explanation: >-
+      Subjective language expresses an opinion rather than a property of the
+      system, so two readers can reasonably disagree about whether the
+      requirement has been satisfied.
+    question_templates:
+      - "What specific, observable behaviour would prove this requirement is satisfied?"
+      - "Who judges this, and what measured value counts as passing?"
+    source: ISO29148
+
+  # --- p.22: "vague pronouns (such as 'it', 'this', 'that')" ---------------
+  - id: AMB-PRON-001
+    phrases: ["it", "this", "that", "they", "them", "these", "those", "such"]
+    category: vague_pronoun
+    category_label: "Vague pronoun"
+    severity: low
+    explanation: >-
+      A pronoun with no explicit antecedent forces the reader to guess which
+      noun it refers to, which permits more than one interpretation.
+    question_templates:
+      - "Which exact noun does this pronoun refer to? Replace the pronoun with that noun."
+    source: ISO29148
+
+  # --- p.22: "ambiguous terms such as adverbs and adjectives (such as
+  #            'almost always', 'significant', 'minimal')" -----------------
+  - id: AMB-ADV-001
+    phrases:
+      ["almost always", "almost never", "significant", "significantly",
+       "minimal", "minimally", "quickly", "rapidly", "fast", "slow", "timely",
+       "approximately", "about", "nearly", "roughly", "several", "some",
+       "many", "few", "various", "sufficient", "sufficiently", "adequate",
+       "adequately", "reasonable", "reasonably", "appropriate",
+       "appropriately", "acceptable", "normal", "typical", "typically",
+       "regularly", "periodically", "frequently", "occasionally", "large",
+       "small", "high", "low", "quality", "as soon as possible",
+       "in real time", "real-time", "instantly", "immediately"]
+    category: ambiguous_modifier
+    category_label: "Ambiguous adverb or adjective"
+    severity: medium
+    explanation: >-
+      Ambiguous adverbs and adjectives describe a degree without a number or a
+      unit, so the threshold that separates pass from fail is undefined.
+    question_templates:
+      - "What exact number, unit, and tolerance replaces this word?"
+      - "At what measured value does this requirement pass, and at what value does it fail?"
+    source: ISO29148
+
+  # --- p.22: "ambiguous logical statements (such as 'or', 'and/or')"
+  #     NOTE 1: consider multiple requirements when encountering these.
+  #     Split into two rules: bare 'and' is far more common in ordinary prose,
+  #     so it carries low severity to keep the signal readable.
+  - id: AMB-LOGIC-001
+    phrases: ["and/or", "or"]
+    category: ambiguous_logic
+    category_label: "Ambiguous logical statement"
+    severity: medium
+    explanation: >-
+      Joining conditions with 'or' or 'and/or' leaves it unclear whether one,
+      several, or all of them are required. The standard advises splitting
+      such a statement into multiple requirements.
+    question_templates:
+      - "Is this one requirement or several? Split it into one statement per testable condition."
+      - "Must every joined condition hold, or is any single one sufficient?"
+    source: ISO29148
+
+  - id: AMB-LOGIC-002
+    phrases: ["and"]
+    category: ambiguous_logic
+    category_label: "Ambiguous logical statement"
+    severity: low
+    explanation: >-
+      A requirement joined by 'and' often hides two separate requirements,
+      each of which needs its own acceptance test.
+    question_templates:
+      - "Does this sentence contain more than one testable requirement? If so, split it."
+    source: ISO29148
+
+  # --- p.22: "open-ended, non-verifiable terms (such as 'provide support',
+  #            'but not limited to', 'as a minimum')" ---------------------
+  - id: AMB-OPEN-001
+    phrases:
+      ["provide support", "support for", "including but not limited to",
+       "but not limited to", "as a minimum", "at a minimum", "and so on",
+       "such as", "among others", "to be determined", "tbd", "etc.", "etc",
+       "and more", "e.g.", "for example"]
+    category: open_ended
+    category_label: "Open-ended, non-verifiable term"
+    severity: high
+    explanation: >-
+      Open-ended terms leave the boundary of the requirement undefined, so it
+      can never be shown to be completely implemented.
+    question_templates:
+      - "List every item this covers. What is explicitly excluded?"
+      - "What is the complete, closed set of cases this requirement applies to?"
+    source: ISO29148
+
+  # --- p.22: "comparative phrases (such as 'better than', 'higher quality')"
+  - id: AMB-COMP-001
+    phrases:
+      ["better than", "worse than", "higher quality", "lower cost",
+       "faster than", "slower than", "more than before", "improved",
+       "enhanced", "superior", "at least as good as", "comparable to",
+       "similar to", "as good as"]
+    category: comparative
+    category_label: "Comparative phrase"
+    severity: high
+    explanation: >-
+      A comparative phrase needs both a named reference point and a
+      measurement method. Without both, the comparison cannot be verified.
+    question_templates:
+      - "Better than what, measured how, and by how much?"
+      - "What is the reference system or previous value being compared against?"
+    source: ISO29148
+
+  # --- p.22: "loopholes (such as 'if possible', 'as appropriate',
+  #            'as applicable')" ---------------------------------------
+  - id: AMB-LOOP-001
+    phrases:
+      ["if possible", "if needed", "if necessary", "if required",
+       "as appropriate", "as applicable", "as required", "as needed",
+       "where feasible", "where possible", "to the extent practical",
+       "to the extent possible", "optionally", "preferably", "ideally"]
+    category: loophole
+    category_label: "Loophole"
+    severity: high
+    explanation: >-
+      A loophole makes the requirement conditional on unstated judgement,
+      which lets an implementation skip it entirely and still claim conformance.
+    question_templates:
+      - "Under exactly which stated condition does this apply? Write that condition as the trigger."
+      - "If the condition is not met, what must the system do instead?"
+    source: ISO29148
+
+  # --- p.22: "terms that imply totality (such as 'all', 'always', 'never',
+  #            'every')". NOTE 2: very difficult to verify. -----------------
+  - id: AMB-TOTAL-001
+    phrases:
+      ["all", "always", "never", "every", "none", "any", "everything",
+       "nothing", "anyone", "everyone", "each and every", "at all times",
+       "100% of the time", "under all circumstances", "completely", "fully",
+       "totally", "entirely"]
+    category: totality
+    category_label: "Term implying totality"
+    severity: medium
+    explanation: >-
+      Terms implying totality are very difficult to verify, because exhaustive
+      testing of every possible case is usually impossible.
+    question_templates:
+      - "Which finite, enumerable set does this actually cover, and how will it be tested?"
+      - "Can this be restated as a measurable rate or a bounded set instead of an absolute?"
+    source: ISO29148
+
+  # --- p.12 "Unambiguous", and the shall/should distinction the standard
+  #     relies on throughout. ---------------------------------------------
+  - id: AMB-MODAL-001
+    phrases:
+      ["should", "may", "might", "could", "can", "would", "will be able to",
+       "is expected to", "are expected to", "ought to", "is supposed to"]
+    category: weak_modal
+    category_label: "Weak modal verb"
+    severity: medium
+    explanation: >-
+      Only 'shall' expresses a binding requirement. A weak modal leaves it
+      unclear whether the behaviour is mandatory, so it may never be
+      implemented or tested.
+    question_templates:
+      - "Is this mandatory? If so, replace the modal verb with 'shall'."
+      - "If it is genuinely optional, move it out of the requirements into a note."
+    source: ISO29148
+
+  # --- p.22: "incomplete references (not specifying the reference with its
+  #            date and version number)" ---------------------------------
+  - id: AMB-REF-001
+    phrases:
+      ["the standard", "the specification", "the document", "the manual",
+       "applicable standards", "relevant standards", "industry standard",
+       "the guidelines", "per the spec", "see documentation"]
+    category: incomplete_reference
+    category_label: "Incomplete reference"
+    severity: medium
+    explanation: >-
+      A reference without its title, date, and version number cannot be
+      resolved to one exact document, so the scope of verification is unclear.
+    question_templates:
+      - "Which exact document, in which dated version, and which clause within it?"
+      - "Which specific parts of that reference apply to this requirement?"
+    source: ISO29148

mcp_reqcheck-0.1.0/src/mcp_reqcheck/server.py

@@ -0,0 +1,561 @@
+"""ReqCheck MCP server.
+
+Finds ambiguous terms in a requirements document, checked against
+ISO/IEC/IEEE 29148:2018. Detection is regex over a versioned catalog -- no
+model is involved, so identical text always produces identical findings, each
+traceable to a numbered rule and a clause of the standard.
+
+Everything lives in this one module on purpose. A client may launch this file
+directly (`mcp run server.py`, where there is no package around it) or through
+the installed console script (`uvx mcp-reqcheck`, where there is). Imports
+between sibling files resolve differently in those two cases, so this file
+imports nothing of its own and both launch styles behave identically.
+
+The rule catalog stays in ambiguity_rules.yaml beside this file: it is data,
+not code, and is read at import.
+
+The catalog and analyser below are copied from apps/api in the ReqCheck web
+application. Rule changes made there need copying here too.
+"""
+
+# Deliberately no `from __future__ import annotations`. It turns every
+# annotation into a string, and dataclasses then resolves those strings via
+# sys.modules[cls.__module__] -- which is None when `mcp run <file>` loads
+# this file directly without registering it as a module. Python 3.13
+# evaluates these annotations natively, so nothing is lost.
+
+import re
+from dataclasses import dataclass
+from re import Pattern
+from pathlib import Path
+from typing import Any
+
+import yaml
+from mcp.server import MCPServer
+
+
+# --------------------------------------------------------------- records
+
+
+@dataclass(frozen=True)
+class Statement:
+    """One requirement sentence, with absolute offsets into the document."""
+
+    index: int
+    text: str
+    start_offset: int
+    end_offset: int
+
+
+@dataclass(frozen=True)
+class Finding:
+    """An exact-span ambiguity issue tied to one catalog rule."""
+
+    rule_id: str
+    category: str
+    severity: str
+    explanation: str
+    source_id: str
+    start_offset: int
+    end_offset: int
+    matched_text: str
+    statement_index: int
+    id: str | None = None
+    status: str = "open"
+
+    @property
+    def length(self) -> int:
+        return self.end_offset - self.start_offset
+
+
+# --------------------------------------------------------------- catalog
+
+
+VALID_SEVERITIES = {"low", "medium", "high"}
+DEFAULT_CATALOG_PATH = Path(__file__).parent / "ambiguity_rules.yaml"
+
+REQUIRED_FIELDS = (
+    "id",
+    "phrases",
+    "category",
+    "severity",
+    "explanation",
+    "question_templates",
+    "source",
+)
+
+
+class CatalogError(Exception):
+    """Raised when the YAML catalog is missing, malformed, or inconsistent."""
+
+
+@dataclass(frozen=True)
+#dataclass here is used to create a simple class that holds data. The frozen=True parameter makes the class immutable, meaning that its attributes cannot be changed after it is created.
+class AmbiguityRule:
+    id: str
+    phrases: tuple[str, ...]
+    category: str
+    category_label: str
+    severity: str
+    explanation: str
+    question_templates: tuple[str, ...]
+    source: str
+    # Annotated without the `re.` prefix: dataclasses resolves dotted
+    # annotations through sys.modules, which `mcp run <file>` does not
+    # populate for a directly-loaded file.
+    pattern: Pattern[str]
+
+
+class AmbiguityRuleCatalog:
+    """C2 - loads, validates, compiles, and serves the versioned rule catalog.
+
+    Behaviour this class owns:
+      - reads a versioned YAML catalog and refuses to load a broken one
+      - rejects duplicate rule ids, invalid severities, and unknown source ids
+      - compiles each rule's phrase list into one word-boundary regex, with
+        longer phrases taking precedence over shorter ones
+      - serves explanations, severities, sources, and question templates to
+        C3 (detection) and C5 (coaching)
+    """
+
+    def __init__(
+        self,
+        catalog_version: str,
+        rules: list[AmbiguityRule],
+        sources: dict[str, dict[str, str]],
+    ) -> None:
+        self._catalog_version = catalog_version
+        self._rules = rules
+        self._sources = sources
+        self._by_id = {rule.id: rule for rule in rules}
+
+    # ---------------------------------------------------------------- load
+
+    @classmethod
+    # a classmethod is used here so that the catalog can be loaded without instantiating the class
+    def from_yaml(cls, path: Path | None = None) -> "AmbiguityRuleCatalog":
+        path = path or DEFAULT_CATALOG_PATH
+        if not path.exists():
+            raise CatalogError(f"Catalog file not found: {path}")
+
+        try:
+            raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError as exc:
+            raise CatalogError(f"Catalog is not valid YAML: {exc}") from exc
+
+        version = raw.get("catalog_version")
+        if not version:
+            raise CatalogError("catalog_version is required")
+
+        sources = raw.get("sources") or {}
+        if not sources:
+            raise CatalogError("at least one source is required")
+
+        entries = raw.get("rules") or []
+        if not entries:
+            raise CatalogError("catalog contains no rules")
+
+        rules: list[AmbiguityRule] = []
+        seen: set[str] = set()
+        for entry in entries:
+            rule = cls._build_rule(entry, sources)
+            #cls here is used to refer to the class itself.
+            if rule.id in seen:
+                raise CatalogError(f"duplicate rule id: {rule.id}")
+            seen.add(rule.id)
+            rules.append(rule)
+
+        return cls(str(version), rules, sources)
+
+    @staticmethod
+    def _build_rule(
+        entry: dict, sources: dict[str, dict[str, str]]
+    ) -> AmbiguityRule:
+        # isinstance here is used to check if the entry is a dictionary. If it is not, a CatalogError is raised.
+        if not isinstance(entry, dict):
+            raise CatalogError(f"rule entry is not a mapping: {entry!r}")
+
+        rule_id = entry.get("id", "<unknown>")
+        for field_name in REQUIRED_FIELDS:
+            if not entry.get(field_name):
+                raise CatalogError(f"rule {rule_id} is missing '{field_name}'")
+
+        severity = entry["severity"]
+        if severity not in VALID_SEVERITIES:
+            raise CatalogError(
+                f"rule {rule_id} has invalid severity '{severity}' "
+                f"(expected one of {sorted(VALID_SEVERITIES)})"
+            )
+
+        source = entry["source"]
+        if source not in sources:
+            raise CatalogError(f"rule {rule_id} cites unknown source '{source}'")
+
+        # Longest phrase first, so 'and/or' beats 'or' and
+        # 'including but not limited to' beats 'but not limited to'.
+        phrases = sorted(
+            {p.strip().lower() for p in entry["phrases"] if str(p).strip()},
+            #key=len here is used to sort the phrases by length in descending order.
+            key=len,
+            reverse=True,
+        )
+        if not phrases:
+            raise CatalogError(f"rule {rule_id} has no usable phrases")
+
+        # (?<!\w) and (?!\w) act as word boundaries that still work when a
+        # phrase begins or ends with punctuation, such as 'etc.' or 'e.g.'.
+        # Plain \b would fail on those because '.' is not a word character.
+
+        #pattern here simply is to compile the phrases into a regular expression pattern that can be used to match the phrases in the text. 
+        #This allows for matching phrases that may contain punctuation or special characters.
+        alternation = "|".join(re.escape(p) for p in phrases)
+        try:
+            pattern = re.compile(rf"(?<!\w)(?:{alternation})(?!\w)", re.IGNORECASE)
+        except re.error as exc:
+            raise CatalogError(f"rule {rule_id} produced an invalid pattern: {exc}") from exc
+
+        # Human-readable name shown in the UI. Falls back to a readable form
+        # of the slug so a rule is never displayed as raw snake_case.
+        category_label = entry.get("category_label") or entry["category"].replace("_", " ").capitalize()
+
+        return AmbiguityRule(
+            id=entry["id"],
+            phrases=tuple(phrases),
+            category=entry["category"],
+            category_label=category_label,
+            severity=severity,
+            explanation=" ".join(str(entry["explanation"]).split()),
+            question_templates=tuple(entry["question_templates"]),
+            source=source,
+            pattern=pattern,
+            #pattern here is used to compile the phrases into a regular expression pattern that can be used to match the phrases in the text.
+            # pattern replaces the phrases.
+        )
+
+    # ---------------------------------------------------------------- query
+    #property here is used to define a read-only attribute that can be accessed like a regular attribute, but is computed on-the-fly when accessed. In this case, it returns the catalog version of the rule catalog.
+    @property
+    def catalog_version(self) -> str:
+        return self._catalog_version
+
+    @property
+    def rules(self) -> list[AmbiguityRule]:
+        return list(self._rules)
+
+    def get(self, rule_id: str) -> AmbiguityRule:
+        if rule_id not in self._by_id:
+            raise CatalogError(f"unknown rule id: {rule_id}")
+        return self._by_id[rule_id]
+
+    def question_templates_for(self, rule_id: str) -> list[str]:
+        return list(self.get(rule_id).question_templates)
+
+    def source_for(self, rule_id: str) -> dict[str, str]:
+        return dict(self._sources.get(self.get(rule_id).source, {}))
+
+    def display_for(self, rule_id: str) -> dict[str, str]:
+        """Human-readable labels for the UI.
+
+        Internal identifiers such as AMB-SUBJ-001 and 'subjective_language'
+        are traceability data, not something a student should have to decode.
+        """
+        try:
+            rule = self.get(rule_id)
+        except CatalogError:
+            # A finding stored under a rule that has since left the catalog.
+            return {
+                "category_label": "Unknown category",
+                "source_label": "Unknown source",
+                "source_clause": "",
+            }
+        source = self._sources.get(rule.source, {})
+        short = source.get("short_name") or source.get("title") or rule.source
+        clause = source.get("clause", "")
+        return {
+            "category_label": rule.category_label,
+            "source_label": f"Cited from {short}",
+            "source_clause": clause,
+        }
+
+    def describe(self) -> dict[str, object]:
+        """Summary used by the UI to show which catalog produced a finding."""
+        return {
+            "catalog_version": self._catalog_version,
+            "rule_count": len(self._rules),
+            "phrase_count": sum(len(r.phrases) for r in self._rules),
+            "sources": self._sources,
+        }
+
+
+# -------------------------------------------------------------- analyser
+
+
+SEVERITY_RANK = {"high": 0, "medium": 1, "low": 2}
+
+# A statement ends at sentence punctuation followed by whitespace, or at any
+# run of newlines (so bulleted or numbered requirement lists split correctly).
+_STATEMENT_BREAK = re.compile(r"(?<=[.!?])\s+|\n+")
+
+
+class AmbiguityAnalyzer:
+    """C3 - deterministic exact-span detection.
+
+    No AI, no network, no randomness, no clock. The same text and the same
+    catalog always produce byte-identical findings, which is what makes the
+    detection explainable and reproducible.
+
+    Behaviour this class owns:
+      - segments a document into statements while preserving absolute offsets
+      - runs every compiled catalog rule over the text
+      - resolves overlaps by a fixed precedence so results never vary
+      - computes exact character offsets for highlighting
+    """
+
+    def __init__(self, catalog: AmbiguityRuleCatalog) -> None:
+        self._catalog = catalog
+
+    @property
+    def catalog_version(self) -> str:
+        return self._catalog.catalog_version
+
+    # ------------------------------------------------------------ segment
+
+    def segment(self, text: str) -> list[Statement]:
+        """Split text into statements, keeping absolute offsets into `text`.
+
+        Offsets are computed from match positions rather than by searching for
+        each chunk, so repeated identical sentences still get correct, distinct
+        offsets.
+        """
+
+        #this method returns all statements(sentence chunks) in the text, with their start and end offsets
+        statements: list[Statement] = []
+        index = 0
+        cursor = 0
+
+        # separator is the match object for the next statement break, which is either
+        # a sentence-ending punctuation followed by whitespace, or any run of newlines.
+        for separator in _STATEMENT_BREAK.finditer(text):
+            chunk = text[cursor : separator.start()]
+            if chunk.strip():
+                statements.append(
+                    Statement(
+                        index=index,
+                        text=chunk,
+                        start_offset=cursor,
+                        end_offset=separator.start(),
+                    )
+                )
+                index += 1
+            cursor = separator.end()
+
+        tail = text[cursor:]
+        if tail.strip():
+            statements.append(
+                Statement(
+                    index=index,
+                    text=tail,
+                    start_offset=cursor,
+                    end_offset=len(text),
+                )
+            )
+
+        return statements
+
+    # ------------------------------------------------------------ analyze
+
+    def analyze(self, text: str) -> list[Finding]:
+        """Return non-overlapping findings, ordered by position."""
+        if not text or not text.strip():
+            return []
+        #statements later is used to find the statement index for each finding, which is needed for context when asking C5 questions.
+        statements = self.segment(text)
+        candidates: list[Finding] = []
+
+        for rule in self._catalog.rules:
+            # instead of phrases, use patterns for actual phrases as specified in rule_catalog
+            # this for loop is to find the matches of the rule's pattern in the text and create Finding objects for each match
+            for match in rule.pattern.finditer(text):
+                start, end = match.start(), match.end()
+                candidates.append(
+                    Finding(
+                        rule_id=rule.id,
+                        category=rule.category,
+                        severity=rule.severity,
+                        explanation=rule.explanation,
+                        source_id=rule.source,
+                        start_offset=start,
+                        end_offset=end,
+                        matched_text=text[start:end],
+                        statement_index=self._statement_index_for(statements, start),
+                        # for each finding, we find the statement index that contains the start offset of the match. This is used for context when asking C5 questions.
+                    )
+                )
+
+        # Fixed precedence, so the result never depends on rule ordering:
+        #   1. earliest start position
+        #   2. longest span      ('as a minimum' beats 'minimum')
+        #   3. highest severity  (high beats medium beats low)
+        #   4. rule id           (alphabetical, purely to break remaining ties)
+        candidates.sort(
+            key=lambda f: (
+                f.start_offset,
+                -f.length,
+                SEVERITY_RANK[f.severity],
+                f.rule_id,
+            )
+        )
+
+        #this for loop is just ot make sure that the findings do not overlap. If a finding overlaps with the previous one, it is discarded.
+        accepted: list[Finding] = []
+        last_end = -1
+        for finding in candidates:
+            if finding.start_offset >= last_end:
+                accepted.append(finding)
+                last_end = finding.end_offset
+        return accepted
+
+
+    def statement_for_offset(self, text: str, offset: int) -> str:
+        """The full statement containing `offset`. Used by C5 for prompt context."""
+        for statement in self.segment(text):
+            if statement.start_offset <= offset < statement.end_offset:
+                return statement.text.strip()
+        return text.strip()
+
+    @staticmethod
+    def _statement_index_for(statements: list[Statement], offset: int) -> int:
+        for statement in statements:
+            if statement.start_offset <= offset < statement.end_offset:
+                return statement.index
+        return 0
+
+
+# ------------------------------------------------------------ mcp server
+
+
+mcp = MCPServer("ReqCheck")
+
+# Built once at import. Loading is pure file IO and the catalog is read-only,
+# so every request reuses the compiled patterns.
+_catalog = AmbiguityRuleCatalog.from_yaml()
+_analyzer = AmbiguityAnalyzer(_catalog)
+
+
+@mcp.tool()
+def ambiguity_analysis(text: str) -> dict[str, Any]:
+    """Find ambiguous terms in a requirements document, checked against
+    ISO/IEC/IEEE 29148:2018.
+
+    Detection is fully deterministic: the same text always returns the same
+    findings, with no model involved and every finding traceable to a numbered
+    rule and a clause of the standard.
+
+    Each finding carries the flagged term, the statement it appears in, why it
+    was flagged, the standard it came from, and question templates for that
+    rule.
+
+    Use the question templates to ask the user what they actually mean --
+    what measurable value, what baseline, whose judgement. Do not rewrite the
+    requirement for them; the point is that they decide the wording.
+
+    Args:
+        text: The requirements document. Plain text -- extract it first if the
+            source is a PDF or Word file.
+    """
+    findings = _analyzer.analyze(text)
+    # Segment once and index it, rather than re-scanning the document for every
+    # finding, which would be quadratic on a long document.
+    statements = {s.index: s.text.strip() for s in _analyzer.segment(text)}
+
+    results: list[dict[str, Any]] = []
+    for finding in findings:
+        display = _catalog.display_for(finding.rule_id)
+        results.append({
+            "matched_text": finding.matched_text,
+            "statement": statements.get(finding.statement_index, ""),
+            "statement_index": finding.statement_index,
+            "rule_id": finding.rule_id,
+            "category": finding.category,
+            "category_label": display["category_label"],
+            "severity": finding.severity,
+            "explanation": finding.explanation,
+            "source_id": finding.source_id,
+            "source_label": display["source_label"],
+            "source_clause": display["source_clause"],
+            "question_templates": list(
+                _catalog.question_templates_for(finding.rule_id)
+            ),
+            # Kept because matched_text alone is ambiguous when the same term
+            # appears more than once; these identify which occurrence.
+            "start_offset": finding.start_offset,
+            "end_offset": finding.end_offset,
+        })
+
+    return {
+        "catalog_version": _catalog.catalog_version,
+        "statement_count": len(statements),
+        "finding_count": len(results),
+        "findings": results,
+    }
+
+
+@mcp.resource(
+    "reqcheck://knowledge-base",
+    name="ReqCheck ambiguity rule catalog",
+    description=(
+        "The full YAML knowledge base: every rule, its phrases, severity, "
+        "explanation, question templates, and ISO/IEC/IEEE 29148 citation."
+    ),
+    mime_type="text/yaml",
+)
+def knowledge_base() -> str:
+    """The rule catalog exactly as authored, including source citations."""
+    return DEFAULT_CATALOG_PATH.read_text(encoding="utf-8")
+
+
+@mcp.prompt(
+    name="check_requirements",
+    title="Check requirements for ambiguity",
+    description=(
+        "Analyse a requirements document with ReqCheck and report every "
+        "ambiguous term with follow-up questions."
+    ),
+)
+def check_requirements(text: str) -> str:
+    """Ask the client to analyse a document and report findings in a fixed shape."""
+    return f"""Use the ReqCheck MCP tool `ambiguity_analysis` to find the ambiguous terms in the requirements below.
+
+Report every finding in exactly this format, numbered, one block per finding:
+
+**N. <matched_text>**
+- Statement: <statement>
+- Location: statement <statement_index> of the document. If the source was a PDF or Word file, give the page and section instead.
+- Source: <source_label>, <source_clause>
+- Severity: <severity>
+- Category: <category_label>
+- Why: <explanation>
+- Questions to answer:
+  1. ...
+  2. ...
+  3. ...
+
+For the questions, adapt the `question_templates` for that finding to this specific statement, using what you know about the document. Ask what measurable value, baseline, or acceptance condition the author means.
+
+Do not rewrite the requirement, and do not suggest a number, unit, or threshold yourself -- ask the author for it. Do not show the question templates verbatim.
+
+If there are no findings, say the document has no terms matching the catalog and note that this checks wording, not completeness.
+
+Here are the requirements:
+
+{text}
+"""
+
+
+def main() -> None:
+    """Entry point for the `mcp-reqcheck` script and `python server.py`."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()