使用说明

数独引擎MCP服务器

提供数独谜题生成和求解功能的示例模型上下文协议（MCP）服务器

一个用Rust开发的示例模型上下文协议（MCP）服务器，提供数独谜题生成和求解功能。该项目演示了如何构建具有显式计算逻辑的MCP服务器来解决难题。

为什么是这样的MCP服务器？

需要遵守法规以确保数据安全和内部部署的企业，同时希望利用人工智能的力量，通常依赖于小型模型。这些模型虽然强大，但有时不足以处理复杂的多步骤逻辑，因此不如高度监管的环境所需的可靠。

关于这个主题的一些参考：

⚠️ 免责声明

该服务器提供数独谜题生成和求解功能，展示谜题求解的计算模式。所有的逻辑都是明确和透明的。

这只是一个演示/示例项目。 这里实现的数独生成和求解逻辑用于教育和演示目的。该软件：

作为MCP服务器实现的技术示例
展示解谜能力
不隶属于任何官方实体

引言

这款数独引擎MCP服务器提供可靠的数独谜题生成和解决能力，可以与人工智能代理集成。与仅依赖LLM推理解决难题不同，此服务器使用 sudokugen crate提供确定性、可验证的数独谜题生成和解决。

🎯 特性

2数独函数：生成数独，求解数独
显式逻辑：使用sudokugen crate进行可靠的谜题生成和解决
稳健的输入验证：演示JSON模式验证和详细的错误处理
灵活的输入格式：接受原始字符串格式或格式化表格格式的谜题
容器化：部署Podman设置示例
Claude桌面集成：MCP集成的MCPB封装示例
专业版本管理：与货物放行自动版本同步
CI/CD管道：全面的GitHub操作工作流程
干净的存储库结构：有组织的脚本和干净的项目布局

📚 快速参考

任务	命令	描述
🧪 测试	`make test`	运行所有测试
🧪 测试SSE	`make test-sse`	使用SSE传输运行MCP服务器
🧪 测试MCP	`make test-mcp`	使用流式HTTP传输运行MCP服务器
🚀 发布	`make release-patch`	创建新的补丁版本
📦 包裹	`make pack`	创建Claude桌面包
🐳 容器	`make image-build`	构建容器映像
ℹ️ 帮助	`make help`	显示所有命令

📋 可用功能

功能	说明	示例
生成器_数独	生成一个随机的经典9x9数独谜题	以81个字符串的形式返回谜题和答案
solve_sudoku	从字符串中解出9x9数独谜题	接受原始或格式化谜题，返回答案

备注：这两个函数都使用 sudokugen 用于可靠生成和解决谜题的板条箱。

示例用法

🎲 生成数独谜题

生成一个新的随机9x9数独谜题：

功能： generate_sudoku

答复：

{
  "puzzle": "...........16..4..2...5.69..3.9.....4.2.8.6.8.56...77583.2...6................",
  "solution": "123456789456789123789123456234567891567891234891234567345678912678912345912345678",
  "puzzle_display": "... | ... | ...\n..1 | 6.. | 4..\n2.. | .5. | 69.\n...\n.3. | 9.. | ...\n..4 | .2. | 8.6\n.8. | 56. | ..7\n...\n758 | 3.2 | ...\n6.. | ... | ...\n... | ... | ...",
  "solution_display": "123 | 456 | 789\n456 | 789 | 123\n789 | 123 | 456\n...\n234 | 567 | 891\n567 | 891 | 234\n891 | 234 | 567\n...\n345 | 678 | 912\n678 | 912 | 345\n912 | 345 | 678",
  "errors": []
}

🧩 解决数独难题

从字符串（原始或格式化）解数独谜题：

功能： solve_sudoku

输入（原始格式）：

puzzle: "...........16..4..2...5.69..3.9.....4.2.8.6.8.56...77583.2...6................"

输入（格式化表格格式）：

puzzle: ". . . | . . . | . . .\n. . 1 | 6 . . | 4 . .\n2 . . | . 5 . | 6 9 .\n------+-------+------\n. 3 . | 9 . . | . . .\n. . 4 | . 2 . | 8 . 6\n. 8 . | 5 6 . | . . 7\n------+-------+------\n7 5 8 | 3 . 2 | . . .\n6 . . | . . . | . . .\n. . . | . . . | . . ."

答复：

{
  "solution": "123456789456789123789123456234567891567891234891234567345678912678912345912345678",
  "solution_display": "123 | 456 | 789\n456 | 789 | 123\n789 | 123 | 456\n...\n234 | 567 | 891\n567 | 891 | 234\n891 | 234 | 567\n...\n345 | 678 | 912\n678 | 912 | 345\n912 | 345 | 678",
  "solved": true,
  "errors": []
}

💡 LLM集成的使用技巧

使用此MCP代理查询LLM时：

生成谜题 -要求生成一个新的数独谜题
解决谜题 -提供任何格式的拼图（原始字符串或格式化表格）
使用自然语言 -无需知道确切的API参数
灵活的输入 -谜题可以以原始字符串或格式化表格的形式提供
获取解决方案 -该工具返回原始解决方案字符串和格式化显示

🚀 快速开始

先决条件

锈蚀1.70+(安装Rust)
货物（含铁锈）
jq 用于JSON处理(安装jq)
cargo-release 对于版本管理： cargo install cargo-release
NodeJS 19+ 必须安装如果你想用以下命令测试服务器 MCP检查员

📥 安装

# Clone the repository
git clone https://github.com/alpha-hack-program/sudoku-engine-mcp-rs.git
cd sudoku-engine-mcp-rs

🏗️ 构建

# Build all servers
make build-all

# Or build individually
make build-sse      # SSE Server
make build-mcp      # MCP HTTP Server
make build-stdio    # STDIO Server for Claude

🧪 单元测试

# Run all tests
make test

🏃‍♂️ 跑步

注：

默认情况下 BIND_ADDRESS=127.0.0.1:8000 为了 上海证券交易所 和 BIND_ADDRESS=127.0.0.1:8001 为了 流式HTTP

但在 生成文件 两者 test-sse 和 test-mcp 设定目标 BIND_ADDRESS=0.0.0.0:8001

# SSE Server (recommended for Llama Stack, being deprecated in MCP Standard)
make test-sse

# MCP Streamable HTTP Server
make test-mcp

# Or directly
RUST_LOG=info BIND_ADDRESS=127.0.0.1:8002 ./target/release/sse_server

🧪 使用MCP检验员进行测试

让我们在一个终端中运行带有SSE传输的MCP服务器：

make test-sse

使用以下命令运行MCP检查器 make inspector:

注：必须安装NodeJS 19+

$ make inspector
npx @modelcontextprotocol/inspector
Starting MCP inspector...
⚙️ Proxy server listening on 127.0.0.1:6277
🔑 Session token: 6f0fdc22e2a9775a95d60c976b37b873bffec1816002fc702ca8ec7186a7c338
Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth

🔗 Open inspector with token pre-filled:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=6f0fdc22e2a9775a95d60c976b37b873bffec1816002fc702ca8ec7186a7c338

🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

打开浏览器，指向预先填充令牌的URL。

确保：

运输类型： SSE
网址： http://localhost:8002/sse

然后单击 connect.

现在点击 List Tools，然后您应该看到工具列表：

最后点击 generate_sudoku 然后单击 Run tool （无需参数）：

恭喜您的数独引擎工具已准备好供启用MCP的代理使用。

📦 Claude桌面集成

包装

# Create MCPB package for Claude Desktop
$ make pack
cargo build --release --bin stdio_server
   Compiling sudoku-engine-mcp-server v0.1.0 (/Users/.../sudoku-engine-mcp-rs)
    Finished `release` profile [optimized] target(s) in 18.23s
Packing MCP server for Claude Desktop...
chmod +x ./target/release/stdio_server
zip -rX sudoku-engine-mcp-server.mcpb -j mcpb/manifest.json ./target/release/stdio_server
updating: manifest.json (deflated 49%)
updating: stdio_server (deflated 63%)

克劳德配置示例

打开克劳德桌面并转到 Settings->Extensions 下降区域。

备注：这展示了MCP集成模式，不适用于实际数据的生产使用。

拖放 MCPB 文件。

点击 Install:

点击 Configure 然后关闭对话框。

您已经准备好了，打开一个新的聊天：

使用以下示例查询“你能为我生成一个新的数独谜题吗？”：

恭喜该工具与Claude Desktop兼容。

🔧 配置

环境变量

# Logging level (debug, info, warn, error)
RUST_LOG=info           

# Or use BIND_ADDRESS directly
BIND_ADDRESS=127.0.0.1:8000

示例用法

生成数独谜题

功能： generate_sudoku

参数： 无（无需参数）

答复：

{
  "puzzle": "...........16..4..2...5.69..3.9.....4.2.8.6.8.56...77583.2...6................",
  "solution": "123456789456789123789123456234567891567891234891234567345678912678912345912345678",
  "puzzle_display": "... | ... | ...\n..1 | 6.. | 4..\n2.. | .5. | 69.\n...\n.3. | 9.. | ...\n..4 | .2. | 8.6\n.8. | 56. | ..7\n...\n758 | 3.2 | ...\n6.. | ... | ...\n... | ... | ...",
  "solution_display": "123 | 456 | 789\n456 | 789 | 123\n789 | 123 | 456\n...\n234 | 567 | 891\n567 | 891 | 234\n891 | 234 | 567\n...\n345 | 678 | 912\n678 | 912 | 345\n912 | 345 | 678",
  "errors": []
}

解决数独难题

功能： solve_sudoku

参数：

{
  "puzzle": "...........16..4..2...5.69..3.9.....4.2.8.6.8.56...77583.2...6................"
}

答复：

{
  "solution": "123456789456789123789123456234567891567891234891234567345678912678912345912345678",
  "solution_display": "123 | 456 | 789\n456 | 789 | 123\n789 | 123 | 456\n...\n234 | 567 | 891\n567 | 891 | 234\n891 | 234 | 567\n...\n345 | 678 | 912\n678 | 912 | 345\n912 | 345 | 678",
  "solved": true,
  "errors": []
}

备注：谜题字符串可以是原始格式（81个字符）或格式化表格格式。格式化字符（空格、换行符、破折号、管道）会自动忽略。

🐳 容器化

构建并运行

这需要 podman 或 docker配置是通过以下方式进行管理的 .env 文件。

# Build container image
scripts/image.sh build

# Run locally
scripts/image.sh run

# Run from remote registry
scripts/image.sh push
scripts/image.sh run-remote

# Show container information
scripts/image.sh info

容器的环境变量

# Production configuration
podman run -p 8001:8001 \
  -e BIND_ADDRESS=0.0.0.0:8001 \
  -e RUST_LOG=info \
  quay.io/atarazana/sudoku-engine-mcp-server:latest

🛠️ 发展

可用命令

🏗️ 构建命令

make build-all              # Build all servers
make build-mcp              # Build MCP server (streamable-http)
make build-sse              # Build SSE server
make build-stdio            # Build stdio server
make pack                   # Pack MCP server for Claude Desktop

🚀 放行命令（货物放行）

make release-patch          # Create patch release (1.0.6 → 1.0.7)
make release-minor          # Create minor release (1.0.6 → 1.1.0)
make release-major          # Create major release (1.0.6 → 2.0.0)
make release-dry-run        # Show what release-patch would do
make sync-version           # Manually sync version to all files

🧪 测试命令

make test                   # Run all tests
make test-sse               # Test SSE server locally
make test-mcp               # Test MCP server locally

🔧 开发命令

make clean                  # Clean build artifacts
make help                   # Show all available commands

项目结构

├── src/                                    # Source code
│   ├── common/
│   │   ├── sudoku_engine.rs              # MCP logic and sudoku functions
│   │   └── mod.rs
│   ├── sse_server.rs                      # SSE Server
│   ├── mcp_server.rs                      # MCP HTTP Server
│   └── stdio_server.rs                    # STDIO Server
├── scripts/                               # Utility scripts
│   ├── sync-manifest-version.sh           # Version sync for cargo-release
│   └── image.sh                          # Container management script
├── mcpb/
│   └── manifest.json                      # Claude Desktop manifest
├── .github/workflows/                     # CI/CD pipelines
│   └── ci.yml                            # GitHub Actions workflow
├── examples/                              # Example code
│   └── generate.rs                        # Example puzzle generation
├── .env                                   # Environment variables
├── Containerfile                          # Container definition
├── Cargo.toml                            # Rust package manifest
└── Makefile                              # Build commands

功能参数

生成器_数独

字段	类型	描述
（无参数）	-	生成不需要参数

响应字段：

字段	类型	描述
`puzzle`	string	生成的谜题为81个字符的字符串（逐行）
`solution`	string	解决方案为81个字符串（逐行）
`puzzle_display`	string	为显示而格式化的拼图
`solution_display`	string	为显示而格式化的解决方案
`errors`	array	生成中的任何错误（如果成功，则为空）

solve_sudoku

字段	类型	描述
`puzzle`	string	数独谜题作为一个字符串（81个字符，数字1-9或“.”表示空单元格，逐行）。可以是原始格式或格式化表格格式。格式化字符（空格、换行符、破折号、管道）会自动忽略。

响应字段：

字段	类型	描述
`solution`	string	已解决的谜题为81个字符的字符串（如果无法解决，则为空）
`solution_display`	string	格式化为显示的解决方案（如果无法解决，则为空）
`solved`	boolean	谜题是否已成功解决
`errors`	array	求解中的任何错误

🔒 安全

输入验证：严格的JSON模式
非root用户：容器以用户身份运行 1001
安全审计: cargo audit 在CI/CD中
最小图像：基于UBI 9最低标准

🤝 贡献

开发工作流程

分叉项目
创建特征分支: git checkout -b feature/new-feature
进行更改和测试: make test
提交更改: git commit -am 'Add new feature'
推送到分支: git push origin feature/new-feature
创建拉取请求

专业发布流程

发展：进行更改，测试 make test
版本颠簸：使用 make release-patch/minor/major
构建：使用 make pack 用于Claude Desktop集成
容器：使用 make image-build 集装箱化

指南

代码质量：关注 cargo fmt 并通过 cargo clippy
测试：添加新功能的测试
版本管理：让货物放行处理版本控制
CI/CD：确保所有GitHub操作都通过
文档：根据需要更新README.md
专业结构：保留脚本 scripts/ 目录

⚙️ 版本管理

此项目使用 货物放行 用于跨所有配置文件自动同步的专业版本管理。

自 Cargo.toml 发布配置：

[package.metadata.release]
# Don't publish to crates.io (since this is a binary project)
publish = false
# Don't push git tags (you can enable this if you want)
push = false
# Run pre-release hook
pre-release-hook = ["scripts/sync-manifest-version.sh"]
# Create git tag with 'v' prefix
tag-name = "v{{version}}"
# Sign tags (optional)
sign-tag = false

🔄 版本同步系统

单一真相来源: Cargo.toml 版本控制一切
自动同步：更新 mcpb/manifest.json 和 .env 自动地
Git集成：自动创建提交和标记

📦 发布工作流

处理你的代码，然后当你满意的时候：

# 1. Make your changes and commit them
git add -A && git commit -m "feat: your changes"

# 2. Create a release (choose appropriate version bump)
make release-patch     # Bug fixes: 1.0.6 → 1.0.7
make release-minor     # New features: 1.0.6 → 1.1.0  
make release-major     # Breaking changes: 1.0.6 → 2.0.0

# 3. Build and package
make pack
make image-build
make image-push

# 4. Push to repository
git push && git push --tags

🔍 预览更改

# See what would happen without making changes
make release-dry-run

🛠️ 手动版本同步（开发）

# Sync version from Cargo.toml to other files manually
make sync-version

💬 LLM查询示例

当将此MCP代理与LLM一起使用时，用户可以提出自然语言问题，从而触发相应的数独工具。以下是现实情况：

🎲 生成数独谜题

示例1：简单拼图生成

查询： “你能为我生成一个新的数独谜题吗？”

结果：

拼图生成成功 ✅
以81个字符串的形式返回谜题和答案
包括拼图和解决方案的格式化显示版本
Puzzle是一个有效的、可解的9x9数独

示例2：生成和显示

查询： “我想要一个新的数独谜题。你能以可读的格式给我看这个谜题吗？”

结果：

拼图生成 带格式化显示
拼图以3x3网格格式显示，带分隔符
还提供格式化显示解决方案
包括原始字符串和格式化显示

示例3：多重谜题

查询： “为我生成三个不同的数独谜题。”

结果：

生成了三个独特的谜题
每个都有自己的谜题和解决方案
所有谜题都是有效且可解的

LLM将使用 generate_sudoku 使用sudokugen板条箱创建新的随机谜题。

🧩 解决数独谜题

示例1：从原始字符串求解

查询： “你能解开这个数独谜题吗：‘…………16..4..2……5.69..3.9……4.2.8.6.8.56……77583.2……6………’？”

结果： ✅ 已解决

解决方案以81个字符串的形式提供
完整解决方案的格式化显示
所有单元格都按照数独规则正确填写

示例2：从格式化表求解

查询： “解决这个难题：

. . . | . . . | . . .
. . 1 | 6 . . | 4 . .
2 . . | . 5 . | 6 9 .
------+-------+------
. 3 . | 9 . . | . . .
. . 4 | . 2 . | 8 . 6
. 8 . | 5 6 . | . . 7
------+-------+------
7 5 8 | 3 . 2 | . . .
6 . . | . . . | . . .
. . . | . . . | . . .
```"

**Result:** ✅ **SOLVED**
- Puzzle parsed successfully (formatting characters ignored)
- Complete solution provided
- Solution verified to be valid

#### Example 3: Unsolvable Puzzle
**Query:** "Solve this puzzle: '123456789234567891345678912456789123567891234678912345789123456891234567912345678'"

**Result:** ❌ **UNSOLVABLE**
- Error: Puzzle violates sudoku rules or has no valid solution
- Detailed error message explaining why it cannot be solved

#### Example 4: Partial Solution Check
**Query:** "I'm working on this sudoku and got stuck. Can you solve it for me? Here's what I have: [provides partial puzzle]"

**Result:** ✅ **SOLVED**
- Takes the partial puzzle
- Completes all empty cells
- Returns full solution with formatted display

#### Sudoku Solving Rules
- **Input Format:** 81 characters (digits 1-9 or '.' for empty cells)
- **Format Flexibility:** Accepts raw strings or formatted tables
- **Validation:** Automatically validates puzzle format and rules
- **Solving:** Uses backtracking algorithm from sudokugen crate
- **Output:** Returns complete solution or error if unsolvable

*The LLM will use `solve_sudoku` with the provided puzzle string, automatically handling formatting, and return the complete solution.*

### 🔄 Complex Multi-Tool Scenarios

#### Example 1: Generate and Verify
**Query:** "Generate a sudoku puzzle, then solve it to verify it's correct."

**Analysis Results:**

**🎲 Puzzle Generation:**
- New puzzle generated
- Puzzle string: `"...........16..4..2...5.69..3.9.....4.2.8.6.8.56...77583.2...6................"`
- Solution string: `"123456789456789123789123456234567891567891234891234567345678912678912345912345678"`

**🧩 Solution Verification:**
- Puzzle solved successfully ✅
- Generated solution matches verification solution
- Puzzle is valid and solvable

**Overall Result:**
- Puzzle generation and solving both work correctly
- Generated puzzles are guaranteed to be solvable

---

#### Example 2: Solve Multiple Puzzles
**Query:** "I have three sudoku puzzles I need solved. Can you solve them all? [provides three puzzle strings]"

**Analysis Results:**

**Puzzle 1:**
- ✅ Solved successfully
- Solution provided

**Puzzle 2:**
- ✅ Solved successfully
- Solution provided

**Puzzle 3:**
- ✅ Solved successfully
- Solution provided

**Summary:**
- All three puzzles solved
- Solutions provided for each
- All puzzles were valid and solvable

*The LLM will use both `generate_sudoku` and `solve_sudoku` tools as needed to provide comprehensive sudoku puzzle generation and solving capabilities.*

## 📄 License

This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.

### CI/CD Pipeline

The project includes a comprehensive GitHub Actions workflow:
- ✅ **Automated Testing**: Unit tests and integration tests
- ✅ **Version Sync Validation**: Tests cargo-release functionality  
- ✅ **Container Building**: Tests containerization process
- ✅ **Artifact Management**: Builds and uploads release artifacts
- ✅ **Cross-platform Support**: Tests on Ubuntu with multiple container runtimes

## 🙋 Support

- **Issues**: [GitHub Issues](https://github.com/alpha-hack-program/sudoku-engine-mcp-rs/issues)
- **Documentation**: [Project Wiki](https://github.com/alpha-hack-program/sudoku-engine-mcp-rs/wiki)
- **CI/CD**: Automated testing and deployment via GitHub Actions

## 🏷️ Tags

`mcp` `model-context-protocol` `rust` `sudoku-engine` `puzzle-solving` `sudoku` `explicit-logic` `claude` `computation-engine` `cargo-release` `professional-rust` `containerization` `ci-cd`

---

**Developed with ❤️ by [Alpha Hack Group](https://github.com/alpha-hack-program)**````