Content
align="center">
# Tool List
**Traditional Chinese Style × Programmer Humor &| Ink-style HTML Astrology Report | Eight Charactersination · Fortune Telling Giving · Programmer's Almanac**
**English** → [docs/README.en.md](./docs/README.en.md)
[](https://github.com/Enoch666/suanming-mcp/stargazers)
[](https://modelcontextprotocol.io)
[](https://www.typescriptlang.org/)
[](https://www.npmjs.com/package/suanming-mcp)
[](./LICENSE)
[](./.md)
</div>
> **Note**: The project is still under continuous iteration. Welcome to Star + Watch for updates, and feel free to raise issues and PRs to join the fun.
---
A MCP (Model Context Protocol) based Astrology Server, **zero external dependencies** (only MCP SDK), generates ink-style HTML astrology reports. Supports **Claude Code**, **Codex**, **OpenCode**, **Cursor**, **Windsurf**, and all MCP compatible tools.
## ✨ Six Astrology Techniques
| Tool | Function | Input | Output | Style |
|------|------|------|------|------|
| `fortune_bazi` | Eight Characters Chart | Birth year, month, day, hour + gender | Four Pillars of Destiny, Five Elements distribution, Day Master analysis, Today's fortune | 🏮 Traditional |
| `fortune_liuyao` | Divination | Question (optional) | Original and changed hexagrams, changed line position, hexagram interpretation | 🏮 Traditional |
| `fortune_qian` | Fortune Telling | Question (optional) | Fortune telling number and poem, seven-word poem, interpretation | 🏮 Traditional |
| `fortune_name` | Name Scoring | Name (2-4 characters) | Five Elements analysis, 81 number theory, three talents configuration, comprehensive score | 🏮 Traditional |
| `fortune_mingming` | Name Giving | Surname + birth date (optional) | 5 candidate names, Five Elements analysis, meaning interpretation | 🏮 Traditional |
| `fortune_coder` | Programmer's Almanac | Programming language | Today's taboos, bug rate/efficiency/fishy index, lucky language | 💻 Fun |
Each astrology result generates an **ink-style HTML page**, automatically opened in the browser, with rice paper texture + brush font + red ink seal.
## 🎨 Ink-style HTML Visual
All astrology results are rendered in a unified ink-style HTML page:
| Visual Element | Implementation |
|---------|------|
| Rice paper texture background | CSS multi-layer noise superposition simulation |
| Brush font title | Google Fonts `Ma Shan Zheng` |
| Regular script | `Noto Serif SC` / `SimSun` |
| Red ink seal | CSS rounded rectangle + 15° rotation, engraved "玄机阁印" |
| Eight trigrams symbols | Unicode native ☰☱☲☳☴☵☶☷ |
| Fading animation | Page loading content gradually appears from ink color |
| Vertical fortune telling | CSS `writing-mode: vertical-rl` |
Color scheme: Rice paper background `#f5f0e8`, dark ink character `#2c2416`, red ink `#c41e1e`, light ink line `#8b7355`.
HTML files are saved in the `~/.suanming/` directory.
## 📸 Preview
### Eight Characters Chart
### Divination
### Fortune Telling
### Name Giving
### Name Scoring
### Programmer's Almanac
*More screenshots in [assets/](./assets/) directory*
## 📦 Installation
```bash
npm install -g suanming-mcp
```
No need to clone the repository, just one command.
### Local Clone (without npm release)
If not released to npm, or want to use the latest code, clone locally:
```bash
git clone https://github.com/Enoch666/suanming-mcp.git
cd suanming-mcp
npm install
npm run build
```
Then point to local `dist/index.js` in `.mcp.json`:
```json
{
"mcpServers": {
"suanming": {
"command": "node",
"args": ["absolute/path/to/dist/index.js"]
}
}
}
```
> **Note**: `args` should be an **absolute path**, e.g., `D:/workspace/study/算命/dist/index.js`. Use forward slashes `/` on Windows, not backslashes `\`.
## ⚙️ Configuration
### Claude Code
Create `.mcp.json` in the project root directory (effective for the current project) or `~/.claude/.mcp.json` (effective globally):
```json
{
"mcpServers": {
"suanming": {
"command": "npx",
"args": ["-y", "suanming-mcp"]
}
}
}
```
### OpenCode
Add to `opencode.yaml`:
```yaml
mcp_servers:
suanming:
command: npx
args:
- "-y"
- suanming-mcp
```
### Cursor / Windsurf / Claude Desktop
Add server configuration in the corresponding MCP configuration file.
Restart the tool after configuration, and the MCP Server will automatically load.
## 🎯 User Guide
Configure and use natural language dialogue to trigger, no need to remember commands:
### Eight Characters Chart `fortune_bazi`
```
Help me calculate my eight characters, born on May 20, 1990, at 10 am, male
Check the eight characters of a female born on January 1, 2000, at 8 am
```
**Input parameters**: `year`, `month`, `day`, `hour` (24-hour clock), `gender` (male/female)
> Eight characters chart page shows year, month, day, and hour pillars, five elements distribution, day master analysis, and today's fortune.
### Divination `fortune_liuyao`
```
Get a divination for my career prospects
Calculate a divination for this relationship
```
**Input parameters**: `question` (optional, default is "fortune")
> Divination page shows original and changed hexagrams, changed line position, and hexagram interpretation.
### Fortune Telling `fortune_qian`
```
Draw a fortune telling for my wealth
Give me a fortune telling
```
**Input parameters**: `question` (optional)
> Fortune telling page shows fortune telling number, seven-word poem, and interpretation.
### Name Scoring `fortune_name`
```
Analyze the name "Zhang San"
Evaluate the name "" score
```
**Input parameters**: `name`-4 characters, required)
> Name scoring page shows five elements analysis, 81 number theory, three talents configuration, and comprehensive score.
### Name Giving `fortune_mingming`
```
Surname Li, born on March 15, 2024, at 8 am, help me come up with some names
Surname Zhang, boy, three-character name
```
**Input parameters**: `surname` (required), `year/month/day/hour` (optional), `gender` (optional)
> Name giving page shows candidate names, five elements analysis, and meaning interpretation.
### Programmer's Almanac `fortune_coder`
```
Is it suitable to write Python today?
Check the programmer's almanac
See today's code fortune
```
**Input parameters**: `language` (required, e.g., Python / JavaScript / Rust / Go)
> Almanac page shows today's taboos, bug rate/efficiency/fishy index, lucky language, and programmer's advice.
## 🏗️ Project Structure
```
suanming-mcp/
├── src/
│ ├── index.ts # MCP Server entry (registers tools + stdio transmission)
│ ├── render/
│ │ └── template.ts # Ink-style HTML template engine
│ ├── data/
│ │ ├── hexagrams.ts # 64 hexagrams complete data
│ │ ├── qianwen.ts # 100 fortune telling poems
│ │ └── characters.ts # 200+ name giving character library + surname stroke table
│ └── tools/
│ ├── bazi-helpers.ts # Shared heavenly stems and earthly branches constants
│ ├── bazi.ts # Eight characters chart
│ ├── liuyao.ts # Divination
│ ├── qian.ts # Fortune telling
│ ├── name.ts # Name scoring
│ ├── mingming.ts # Name giving
│ └── coder.ts # Programmer's almanac
├── assets/ # Screenshots and previews
├── docs/ # Documentation
├── SK # Agent Skill definition
├── package.json
├── tsconfig.json
└── README.md
```
## 🔧 Local Development
```bash
git clone https://github.com/Enoch666/suanming-mcp.git
cd suanming-mcp
npm install
npm run build # Compile TypeScript → dist/
npm start # Start MCP Server (stdio mode)
```
### Smoke Test
```bash
node -e "
const { fortuneCoder } = require('./dist/tools/coder.js');
fortuneCoder({ language: 'Python' }).then(r => {
console.log(r.summary);
console.log('HTML:', r.htmlPath);
});
"
```
## 📤 Publish to npm
```bash
npm login # First: register on npmjs.com for free
npm run build # Ensure dist/ is up-to-date
npm publish # One-line command to publish
```
Users can use it with `npx -y suanming-mcp` after publishing.
## 🎯 Applicable Scenarios
| Scenario | Applicability | Description |
|------|----------|------|
| Learning traditional astrology | Very suitable | Understand from eight characters chart, divination, fortune telling, and more |
| Programmer daily fun | Very suitable | Programmer's almanac is humorous and suitable for team relaxation |
| Name giving reference | Suitable | Generate candidate names with five elements complement, five-grid scoring auxiliary decision |
| Entertainment | Very suitable | Fortune telling, almanac, and fun, play with friends |
| Professional astrology | Not suitable | Only for entertainment, no personalized astrology advice |
| Medical diagnosis | Absolutely not suitable | Astrology ≠ medical behavior, please go to the hospital for physical discomfort |
## ⚠️ Disclaimer
This project is for entertainment and learning reference only. For important decisions related to medical, investment, law, and other fields, please consult relevant professionals. See [docs/USE_AND_RISK_NOTICE.md](./docs/USE_AND_RISK_NOTICE.md) for details.
## Welcome to raise PRs, and contribute More programmer humor- Fortune telling library expansion
giving character- New astrology techniques
- Visual optimization
## 📄 License © 2026
---
<p align="center">
<sub>Made with 🔮玄机阁 | For entertainment only, be superstitious</sub>
</p>
