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
```
