# mcp-ts

**Repository Path**: qfmx/mcp-ts

## Basic Information

- **Project Name**: mcp-ts
- **Description**: mcp测试demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔮 MCP 运势测算服务

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.2-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.org/)
[![Spring AI](https://img.shields.io/badge/Spring%20AI-1.1.2-blue.svg)](https://spring.io/projects/spring-ai)
[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-purple.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> 基于 Spring AI MCP 协议的智能运势测算服务，集成生辰八字、手机号吉凶、星座运势等多种传统命理分析工具。

## 📋 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [技术架构](#技术架构)
- [快速开始](#快速开始)
- [API 文档](#api-文档)
- [配置说明](#配置说明)
- [部署指南](#部署指南)
- [开发计划](#开发计划)

## 🎯 项目简介

本项目是一个基于 **Model Context Protocol (MCP)** 协议的智能运势测算服务端，采用 Spring Boot + Spring AI 构建。通过标准化的 MCP 接口，为 AI 助手提供丰富的传统命理分析能力，包括：

- 📱 **手机号吉凶分析** - 基于数字能量学的号码运势评估
- 🎂 **生辰八字测算** - 结合八字、星座、五行、周易的综合命理分析
- ☀️ **天气查询服务** - 基础天气信息获取

MCP (Model Context Protocol) 是 Anthropic 推出的开放协议，旨在标准化 AI 模型与外部工具、数据源的集成方式。

## ✨ 功能特性

### 1. 手机号吉凶分析 (`analyzePhoneNumber`)

基于中国传统数字能量学，对手机号码进行全方位运势分析：

| 分析维度 | 说明 |
|---------|------|
| 数字含义 | 0-9 每个数字的吉凶寓意解读 |
| 综合评分 | 0-100 分的量化运势评分 |
| 吉凶等级 | 大吉/吉/中平/凶 四级评定 |
| 尾号分析 | 特殊组合识别（888、666、168等） |
| 开运建议 | 个性化使用建议 |

**评分算法**：
- 基础分 60 分
- 吉利数字加分：8(+5)、6(+4)、9(+3)
- 凶数减分：4(-5)
- 特殊组合加成：888(+15)、666(+10)、168(+10)等

### 2. 生辰八字测算 (`analyzeBirthChart`)

融合中国传统命理学与西方占星术的综合分析系统：

#### 核心算法

**八字计算**：
- 年柱：`(年份 - 4) % 60`
- 月柱：基于年干和月份的干支推算
- 日柱：基于基准日期的干支计算
- 时柱：根据日干和出生时辰推算

**五行分析**：
- 天干五行：甲乙木、丙丁火、戊己土、庚辛金、壬癸水
- 地支五行：子亥水、寅卯木、巳午火、申酉金、辰戌丑未土
- 旺衰判定：统计八字中各五行出现次数

**八卦命卦**：
- 基于日柱干支计算命卦
- 乾、坤、震、巽、坎、离、艮、兑八卦解读

#### 分析维度

| 维度 | 内容 |
|------|------|
| 生肖属相 | 中国十二生肖 |
| 西方星座 | 十二星座及特质分析 |
| 生辰八字 | 四柱八字排盘 |
| 五行旺衰 | 金木水火土平衡分析 |
| 命卦解读 | 周易八卦卦象及寓意 |
| 性格特质 | 基于日主的个性分析 |
| 事业财运 | 适合行业及财运走势 |
| 感情婚姻 | 星座配对及感情建议 |
| 健康提示 | 五行对应脏腑养生 |
| 开运建议 | 幸运颜色/数字/方位/贵人 |

### 3. 天气查询 (`getWeather`)

基础天气信息查询服务（示例工具）。

## 🏗️ 技术架构

### 技术栈

- **框架**: Spring Boot 3.3.2
- **JDK**: Java 17
- **AI 框架**: Spring AI 1.1.2
- **协议**: Model Context Protocol (MCP) Streamable HTTP
- **构建工具**: Maven
- **响应式编程**: Spring WebFlux

### 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                      MCP Client                             │
│              (Claude Desktop / Cursor / 其他)                │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP/Streamable HTTP
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   MCP Server                                │
│              Spring Boot Application                        │
│  ┌──────────────┬──────────────┬─────────────────────────┐  │
│  │  Weather     │   Phone      │     Bazi                │  │
│  │  Service     │   Number     │    Service              │  │
│  │              │   Service    │                         │  │
│  └──────────────┴──────────────┴─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

### MCP 协议实现

本项目采用 **Streamable HTTP** 传输方式，支持：
- 工具发现 (Tool Discovery)
- 同步/异步工具调用
- 结构化输入输出
- 错误处理机制

## 🚀 快速开始

### 环境要求

- JDK 17 或更高版本
- Maven 3.6+
- (可选) 支持 MCP 的客户端（如 Claude Desktop）

### 1. 克隆项目

```bash
git clone https://gitee.com/qfmx/mcp-ts.git
cd mcp-server
```

### 2. 编译运行

```bash
# 编译项目
mvn clean compile

# 运行服务
mvn spring-boot:run
```

服务启动后，MCP 端点地址为：`http://localhost:8080/api/mcp`

### 3. 客户端配置

#### Claude Desktop 配置

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "fortune-server": {
      "url": "http://localhost:8080/api/mcp",
      "transport": "streamable-http"
    }
  }
}
```

配置文件位置：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`

#### Cursor 配置

在 Cursor 设置中添加 MCP 服务器：
- Name: `fortune-server`
- URL: `http://localhost:8080/api/mcp`
- Transport: `Streamable HTTP`

## 📖 API 文档

### 工具列表

| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `getWeather` | 查询城市天气 | `cityName` (string): 城市名称 |
| `analyzePhoneNumber` | 手机号吉凶分析 | `phoneNumber` (string): 11位手机号 |
| `analyzeBirthChart` | 生辰八字测算 | `birthDate` (string): 出生日期 yyyy-MM-dd<br>`birthTime` (string, 可选): 出生时间 HH:mm |

### 使用示例

#### 示例 1: 手机号吉凶分析

**请求**：
```json
{
  "tool": "analyzePhoneNumber",
  "params": {
    "phoneNumber": "13888886666"
  }
}
```

**响应**：
```
📱 手机号：13888886666

🌟 大吉

📊 综合评分：95/100

📝 评价：此号码能量极佳，有助于事业发展和财运亨通，是难得的吉祥号码！

🔢 数字含义分析：
   1 - 唯一、开始
   3 - 生、生发
   8 - 发、发财
   ...

🔚 尾号分析：尾号6666 - 六六大顺，事事顺心

💡 建议：这是一个非常吉祥的号码，建议长期使用，有助于提升运势！
```

#### 示例 2: 生辰八字测算

**请求**：
```json
{
  "tool": "analyzeBirthChart",
  "params": {
    "birthDate": "1990-05-20",
    "birthTime": "14:30"
  }
}
```

**响应**：
```
🎂 生辰八字测算报告

📅 出生日期：1990-05-20 14:30

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🐉 生肖属相：马

⭐ 西方星座：金牛座 ♉

📜 生辰八字：庚午 辛巳 壬戌 丁未

🌿 五行分析：金(旺) 木(弱) 水(平) 火(旺) 土(平) | 主属性：金

☯  八卦命卦：乾卦 - 天行健，君子以自强不息

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔮 运势详解：

【性格特质】
水主智，为人聪明机智，善于变通，有洞察力，但有时优柔寡断。

【事业财运】
适合从事金融、法律、机械、军警等行业。财运稳健，宜守不宜攻。

【感情婚姻】
土象星座，感情稳定务实，宜找踏实可靠的伴侣，注意表达情感。

【健康提示】
注意肾脏、泌尿系统健康，宜多食黑色食物，如黑豆、黑芝麻等。

【开运建议】
1. 幸运颜色：黑色、蓝色
2. 幸运数字：3, 6
3. 吉利方位：西北方
4. 贵人属相：猴、鸡
```

## ⚙️ 配置说明

### application.yml

```yaml
server:
  port: 8080

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: fortune-mcp-server
        version: 1.0.0
        endpoint: /api/mcp
        transport: streamable-http

logging:
  level:
    org.springframework.ai: DEBUG
    com.example.mcp: DEBUG
```

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SERVER_PORT` | 服务端口 | 8080 |
| `MCP_ENDPOINT` | MCP 端点路径 | /api/mcp |
| `LOG_LEVEL` | 日志级别 | INFO |

## 🚢 部署指南

### Docker 部署

```dockerfile
FROM eclipse-temurin:17-jdk-alpine
WORKDIR /app
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
```

构建并运行：
```bash
docker build -t mcp-fortune-server .
docker run -p 8080:8080 mcp-fortune-server
```

### 生产环境建议

1. **使用反向代理**（Nginx/Traefik）处理 HTTPS
2. **配置健康检查端点**：`/actuator/health`
3. **启用日志收集**：集成 ELK 或 Loki
4. **监控告警**：集成 Prometheus + Grafana

## 📅 开发计划

- [x] 手机号吉凶分析
- [x] 生辰八字测算
- [x] 天气查询服务
- [ ] 姓名五格分析
- [ ] 塔罗牌占卜
- [ ] 周公解梦
- [ ] 每日运势推送
- [ ] 八字合婚匹配

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目基于 [MIT](LICENSE) 许可证开源。

## 🙏 致谢

- [Spring AI](https://spring.io/projects/spring-ai) - AI 应用开发框架
- [Model Context Protocol](https://modelcontextprotocol.io/) - 开放协议标准
- [Anthropic](https://www.anthropic.com/) - Claude AI 及 MCP 协议

---

<p align="center">
  Made with ❤️ by MCP Fortune Team
</p>