Metadata-Version: 2.5
Name: souyun-mcp
Version: 0.1.0
Summary: MCP (stdio) server for the sou-yun.cn 律诗/绝句 格律校验 (poem meter & rhyme checker)
Project-URL: Homepage, https://github.com/okclip/souyun-mcp
Project-URL: Source, https://github.com/okclip/souyun-mcp
Author: okclip
License-Expression: MIT
License-File: LICENSE
Keywords: chinese-poetry,mcp,model-context-protocol,souyun,平仄,律诗,格律
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx>=0.27
Requires-Dist: lxml>=5.0
Requires-Dist: mcp<2,>=1.2.0
Description-Content-Type: text/markdown

# souyun-mcp

A Python **stdio MCP server** that wraps the sou-yun.cn 律诗校验 tool
(<https://www.sou-yun.cn/manalyzepoem.aspx>), which checks the 平仄 and rhyme of Chinese regulated verse (律诗 / 绝句).

## Tool

### `check_poem`

| arg | default | description |
|---|---|---|
| `poem` | (required) | Full poem text with punctuation, one poem per call |
| `rhyme_book` | `"ty"` | `"ty"` = 中华通韵 (manalyzepoem.aspx), `"psy"` = 平水韵 (analyzepoem.aspx) |
| `enable_self_jiu` | `true` | Allow 本句自救 |
| `enable_other_jiu` | `false` | Allow 对句相救 |
| `include_rhyme_chars` | `false` | Include the (long) list of characters in the rhyme group |
| `max_suggestions` | `40` | Max replacement words listed per problem |
| `output_format` | `"text"` | `"text"` report, or `"json"` structured data |

The output includes the form and rhyme (e.g. `五言律诗 押侵韵`), the 平仄 line for each couplet, characters flagged as
`平仄有误` / `用韵错误` / `多音字需自校` with their sentence and position, notes like 孤平/三平尾/失粘/拗救, repeated-character
warnings, details for polyphonic and out-of-rhyme characters, and suggested replacement words.

## Install / run

From PyPI (no clone needed):

```bash
uvx souyun-mcp          # run directly with uv
pip install souyun-mcp  # or install, then run `souyun-mcp`
```

From source:

```bash
cd w:\fun_workspace\souyun-mcp
uv sync            # or: pip install -e .
uv run souyun-mcp  # starts the stdio server (normally your MCP client launches it)
```

## MCP client config

Cline / Claude Desktop / Cursor (`mcpServers` JSON), using the PyPI package:

```json
{
  "mcpServers": {
    "souyun": { "command": "uvx", "args": ["souyun-mcp"] }
  }
}
```

From a local checkout:

```json
{
  "mcpServers": {
    "souyun": {
      "command": "uv",
      "args": ["--directory", "w:\\fun_workspace\\souyun-mcp", "run", "souyun-mcp"]
    }
  }
}
```

Without uv, after `pip install -e .`:

```json
{ "mcpServers": { "souyun": { "command": "python", "args": ["-m", "souyun_mcp"] } } }
```

## Test

```bash
uv run python tests/smoke_test.py
```

## Notes

- This tool scrapes the public web page, so it can break if sou-yun.cn changes its HTML. Please use it moderately.
- The site rejects requests that don't send a browser User-Agent, so the client sends one.
