Skip to main content
Glama
MaoBui2907

tuvi-mcp

by MaoBui2907
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

TuVi MCP - Máy Bói Toán Việt Nam

Một MCP (Model Context Protocol) server cung cấp các công cụ bói toán dựa trên lịch âm Việt Nam, sử dụng các yếu tố như Can Chi, Ngũ Hành, Xung Khắc, và các phương pháp bói toán truyền thống.

Tính năng

1. Chi Tiết Ngày Sinh (get_date_of_birth_detail)

Phân tích chi tiết ngày sinh bao gồm:

  • Ngày âm lịch

  • Tuổi Can Chi (Can + Chi)

  • Ngũ Hành mệnh

  • Nạp Âm

  • Quái số

  • Phật Đồ Mạng

  • Cung Phi (hướng tốt)

2. Dự Đoán Vận Hạn Hàng Ngày (get_daily_fortune)

Dự đoán vận hạn dựa trên tương quan giữa ngày sinh và ngày cần xem:

  • Quan hệ tổng thể

  • Quan hệ Can

  • Quan hệ Chi

  • Quan hệ Ngũ Hành

3. Dự Đoán Vận Hạn Chung (get_general_fortune)

Thông tin vận hạn chung cho mọi người trong ngày:

  • Ngày âm lịch và tiết khí

  • Can Chi ngày

  • Hướng Tài Thần, Hỷ Thần, Quý Nhân

  • Trực ngày

  • Phận Can, Phận Chi

  • Nhi thập bát tú

  • Thập nhị kiến trừ

  • Lục diệu

Related MCP server: Lunar Calendar MCP Server

Cài đặt

Yêu cầu hệ thống

  • Python 3.12+

  • PDM (Python Dependency Manager)

Các bước cài đặt

  1. Clone repository:

    git clone <repository-url>
cd tuvi-mcp

  2. Cài đặt dependencies:

    pdm install

  3. Cài đặt package:

    pdm build
pip install dist/tuvi_mcp-0.1.0.tar.gz

Sử dụng

Chạy MCP Server

Sau khi cài đặt, bạn có thể chạy MCP server bằng:

tuvi-mcp

Sử dụng trong ứng dụng MCP

Server này tuân theo Model Context Protocol và có thể được tích hợp vào các ứng dụng hỗ trợ MCP như Claude Desktop, VS Code, etc.

Cấu hình FastMCP Server

Chạy trực tiếp

Sau khi cài đặt package, bạn có thể chạy server trực tiếp:

tuvi-mcp

Cấu hình với Claude Desktop

Thêm vào file cấu hình Claude Desktop (claude_desktop_config.json):

Trên macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Trên Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tuvi-mcp": {
      "command": "tuvi-mcp"
    }
  }
}

Cấu hình với VS Code (Cursor)

Thêm vào file settings VS Code/Cursor:

{
  "mcp": {
    "servers": {
      "tuvi-mcp": {
        "command": "tuvi-mcp"
      }
    }
  }
}

Chạy trong Development Mode

Khi phát triển, bạn có thể chạy server trực tiếp từ source:

Cách 1: Chạy trực tiếp với Python

# Từ thư mục gốc của project
python -m src.main

Cách 2: Sử dụng PDM script (khuyến nghị)

# Cài đặt dependencies nếu chưa có
pdm install

# Chạy server với script đã định nghĩa
pdm run dev

Cách 3: Cài đặt package ở chế độ editable

# Cài đặt package ở chế độ development
pdm install

# Sau đó có thể chạy như đã cài đặt
tuvi-mcp

Kiểm tra server hoạt động

Test với MCP Inspector (khuyến nghị):

# Cài đặt MCP Inspector
pip install mcp-inspector

# Chạy inspector và kết nối với server
mcp-inspector python -m src.main

Hoặc test với MCP CLI:

# Cài đặt mcp CLI (nếu chưa có)
pip install mcp

# Test server (cần cài đặt package trước)
pip install -e .
mcp dev tuvi-mcp

Ví dụ sử dụng

from src.main import mcp

# Lấy chi tiết ngày sinh
result = mcp.call_tool("get_date_of_birth_detail", {
    "date_of_birth": "1998-07-19",
    "gender": 1,
    "format": "text"
})

# Dự đoán vận hạn hàng ngày
result = mcp.call_tool("get_daily_fortune", {
    "date_of_birth": "1998-07-19",
    "forecast_day": "2024-12-24",
    "format": "text"
})

# Dự đoán vận hạn chung
result = mcp.call_tool("get_general_fortune", {
    "forecast_day": "2024-12-24",
    "format": "json"
})

API Reference

get_date_of_birth_detail

Parameters:

  • date_of_birth (string): Ngày sinh theo định dạng YYYY-MM-DD

  • gender (int, optional): Giới tính (1: nam, 0: nữ), mặc định là 1

  • format (string, optional): Định dạng trả về ("text" hoặc "json"), mặc định là "text"

Returns: Chi tiết ngày sinh dưới dạng text hoặc JSON

get_daily_fortune

Parameters:

  • date_of_birth (string): Ngày sinh theo định dạng YYYY-MM-DD

  • forecast_day (string, optional): Ngày cần dự đoán, mặc định là hôm nay

  • format (string, optional): Định dạng trả về ("text" hoặc "json"), mặc định là "text"

Returns: Dự đoán vận hạn hàng ngày

get_general_fortune

Parameters:

  • forecast_day (string, optional): Ngày cần dự đoán, mặc định là hôm nay

  • format (string, optional): Định dạng trả về ("text" hoặc "json"), mặc định là "text"

Returns: Dự đoán vận hạn chung

Dependencies

  • fastmcp (>=2.14.1): Framework cho MCP server

  • lunardate (>=0.2.2): Xử lý ngày âm lịch

  • lunar-python (>=1.4.8): Thư viện lịch âm Trung Quốc/Việt Nam

Kiến trúc dự án

src/
├── main.py           # Entry point và định nghĩa MCP tools
├── libs/
│   ├── can_chi.py    # Các hàm liên quan đến Can Chi, Ngũ Hành
│   ├── lunar_date.py # Xử lý ngày âm lịch
│   ├── xung_khac.py  # Tính toán xung khắc
│   └── khuyen.py     # Các bảng khuyên, phán đoán
└── tools/            # Các công cụ bổ sung

Phát triển

Chạy tests

python -m pytest tests/

Chạy development server

python src/main.py

Đóng góp

Mời đóng góp bằng cách tạo Issue hoặc Pull Request trên GitHub.

Giấy phép

MIT License - Xem file LICENSE để biết thêm chi tiết.

Lưu ý

Thông tin được cung cấp chỉ mang tính tham khảo và giải trí. Không nên sử dụng để đưa ra quyết định quan trọng trong cuộc sống.

Available Tools

3 tools
get_daily_fortuneB

Get a daily fortune based on the date of birth and the forecast day

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoThe format to return the fortune in, either "text" or "json", default is "text"text
forecast_dayNoThe day to forecast the fortune for, in the format of YYYY-MM-DD, default is today2026-08-13
date_of_birthYesThe date of birth in the format of YYYY-MM-DD

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits, but it only states the operation and inputs. It does not explain whether the fortune is random, how errors are handled, or any side effects, representing a significant transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no filler, front-loading the core action. It is appropriately concise for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The input schema is complete and an output schema exists, so the description is largely sufficient for invocation. However, it lacks usage context and behavioral details, which are captured in other dimensions, making it adequate but not excellent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage with detailed descriptions for all three parameters, including defaults and format. The description merely restates the parameters without adding any extra meaning, so it meets the baseline for schema-heavy coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to get a daily fortune using date of birth and forecast day. It uses a specific verb 'get' and identifies the resource, but does not explicitly differentiate from sibling tools like get_general_fortune or get_date_of_birth_detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings. There is no mention of alternatives, exclusions, or contextual triggers, leaving the agent without direction on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_date_of_birth_detailC

Get the detail of the date of birth

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoThe format to return the detail in, either "text" or "json", default is "text"text
genderNoThe gender of the person, 1 for male, 0 for female
date_of_birthYesThe date of birth in the format of YYYY-MM-DD

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. However, it does not mention that it is likely read-only, what data it relies on (date of birth and gender), or what the output looks like beyond the schema. The description adds little transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, but it is under-specified and does not earn its place by conveying enough information. It is not concise in a useful way; it is simply minimal and vague.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has three parameters, an output schema, and related sibling tools, the description lacks context on what 'detail' means, when to prefer this tool, and what the output represents. It is barely adequate for a basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents all three parameters with clear descriptions (100% coverage), so the baseline is 3. The description itself does not add extra meaning about how format or gender affect the result, but it does not need to compensate significantly given the schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the action ('get') and the resource ('date of birth'), but 'the detail' is vague and does not specify what details are returned or how it differs from sibling fortune tools. It is not a tautology, but it lacks specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the sibling tools (get_daily_fortune, get_general_fortune). The description does not mention any alternatives, prerequisites, or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_general_fortuneA

Get a general fortune for everyone based on the forecast day

ParametersJSON Schema
NameRequiredDescriptionDefault
formatNoThe format to return the fortune in, either "text" or "json", default is "text"text
forecast_dayNoThe day to forecast the fortune for, in the format of YYYY-MM-DD, default is today2026-08-13

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It correctly implies a read-only operation via 'Get' and adds the 'for everyone' scope, but it does not disclose any limitations, potential side effects, or output format nuances beyond what the schema already captures. This is adequate for a simple, non-destructive get tool but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no filler. It front-loads the action and scope, making it easy to parse, and is appropriately sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is simple (two optional params, output schema exists), the description is mostly complete. It captures the core purpose and scope, and the output schema covers return values. However, it lacks explicit differentiation from sibling tools and any note about when to use it over those, which would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both parameters (format and forecast_day) fully described in the schema. The description merely reinforces the forecast_day parameter ('based on the forecast day') without adding syntax or behavior details, so it adds no meaningful value over the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('general fortune') and clarifies scope ('for everyone'), which distinguishes it from sibling tools likely focused on individual or date-of-birth-specific fortunes. This is a clear, non-ambiguous purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, and it does not mention any exclusions or prerequisites. It simply states what the tool does without contextualizing its role relative to the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.1
    • First observedget_daily_fortune
    • First observedget_date_of_birth_detail
    • First observedget_general_fortune
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a clear, non-overlapping purpose: one returns details about a birth date, one provides a personalized daily fortune, and one gives a general daily fortune. There is no ambiguity in what each tool does.

Naming Consistency5/5

All tool names follow the 'get_' prefix followed by a descriptive noun: get_date_of_birth_detail, get_daily_fortune, get_general_fortune. The pattern is uniform and predictable.

Tool Count5/5

With exactly 3 tools, the set is lean but covers the core functions of a fortune-telling service without unnecessary bloat. Each tool earns its place and the count is within the ideal 3-15 range.

Completeness5/5

The domain (fortune-telling based on birth date) is fully addressed: detail extraction, personalized fortune, and general fortune. There are no obvious dead ends or missing operations for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Bazi MCP

    shuangzixing1976
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for accurate Bazi calculations, enabling personality analysis, destiny forecasting, and Chinese calendar queries via AI agents.
    108 npm
    ISC

  • Saju Concierge

    bb4rjfl
    F
    license
    Not graded
    quality
    B
    maintenance
    MCP server that calculates saju (four pillars) from birth date/time and provides entertaining interpretations of daily fortune, yearly luck, compatibility, name analysis, and tarot using MIT-licensed manseryeok-js.
    -

  • Agentic Player 10 Saju MCP

    Bombay
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server that generates fortune context packs based on Saju, Zi Wei Dou Shu, and Western astrology for AI interpretation, enabling reflective entertainment and structured self-counseling in KakaoTalk conversations.
    AGPL 3.0