Content
# wps-mcp-rust
Local **stdio MCP** service: Process `.docx` / `.xlsx` / text files in pure Rust, and support listing and extracting embedded docx/xlsx from host documents.
> The name contains WPS, and the implementation strategy is local open format processing, **not** controlling WPS client, **not** calling cloud API.
## Function Overview
| Category | Tool |
|------|------|
| Text | `text_read`, `text_write`, `text_info` |
| Word | `docx_read_text`, `docx_read_tables`, `docx_to_markdown`, `docx_create`, `docx_replace_text` |
| Excel | `xlsx_list_sheets`, `xlsx_read`, `xlsx_to_csv`, `xlsx_write`, `xlsx_update_cells` |
| Embedded | `doc_list_embeddings`, `doc_extract_embedding` |
| Others | `ping` |
Agreement Summary (see design document for details):
- **Path**: Prefer absolute path; relative path is relative to process CWD
- **Write operation**: Do not overwrite existing target by default; allow overwrite when writing back to source file or `overwrite=true` (text)
- **Large result**: `xlsx_read` / `text_read` support `limit`/`offset` (default about 5000 lines), return `truncated`
- **Encoding**: Text automatically try UTF-8 / GBK / GB18030, lossy decode when failed
- **Excel range**: `xlsx_read.range` support A1 style (e.g., `A1:C10`)
- **Embedded object**: Only list/extract one layer, **not write back** to host
Tool `description` / `inputSchema` and server `instructions` have been optimized for Agent intent: including "read / parse / read / analyze / summarize / extract" and other trigger words, and specify `path` needs to pass local absolute or relative path.
## Build
```bash
cargo build --release
```
Binary: `target/release/wps-mcp-rust`
## Access Cursor / Claude Desktop
```json
{
"mcpServers": {
"wps-mcp-rust": {
"command": "/absolute/path/to/wps-mcp-rust/target/release/wps-mcp-rust",
"args": []
}
}
}
```
Logs go to **stderr** by default (`RUST_LOG=info`), avoiding pollution of MCP's stdout protocol stream.
## Development
```bash
cargo test
cargo fmt
cargo clippy
```
Use `cargo run --example make_fixtures` to regenerate `tests/fixtures/sample.xlsx`.
## Limitations (Phase 1)
- Do not support PPT, encrypted documents, `.doc` / `.xls`
- Do not make complete style fidelity
- Embedded objects only support listing and extracting, **not write back** to host
- `docx_replace_text` may not replace cross-run text on complex documents split by run
- `xlsx_read` supports A1 range (e.g., `A1:C10`); read whole table by default, default `limit=5000` pagination
- `xlsx_to_csv` exports in full, not limited by `xlsx_read` default line count
## License
MIT
