mcp-tung-shing

This MCP server provides Chinese Almanac (Tong-Sheng) calculations and information. It supports converting between Gregorian and lunar calendars, providing daily auspicious/inauspicious guidance, hourly (shi chen) fortunes, and other traditional metaphysical elements such as 五行 and星宿. The primary tool exposed is get-tung-shing, which retrieves 黄历 data for a specified date range and can include hourly information. To use it, call the tool within your MCP configuration and pass parameters to tailor the results to your needs. The tool returns structured data about the chosen date(s) including宜忌 details, and can filter results by specific types of 宜 or 忌 if you need to narrow down the output.

Tools available:

• get-tung-shing: fetch 黄历 information for a given startDate; optionally includeHours for hourly fortunes; specify days to extend the date range; apply tabooFilters to filter宜忌 items by type (1 for 宜, 2 for 忌) and value to match specific items.

Example usage scenarios include:

• Retrieve today's黄历 with default settings.
• Retrieve the next 7 days with hourly information and filter to show only certain 宜忌 items.
• Retrieve data for a specific date range and inspect 农历 converted dates, 吉凶宜忌, and 时辰信息.

Prerequisites:

• Node.js (recommended: LTS, v14+)
• npm or pnpm

Installation steps:

1. Ensure you have Node.js and npm installed. Verify:

node -v
npm -v

2. In your MCP configuration, add the Tung-Shing server entry as shown in the README. You can also test directly using npx:

npx -y mcp-tung-shing@latest

This will fetch the latest mcp-tung-shing package and start the MCP server in your environment (as configured).

3. If you’re managing MCP servers via a central config, place the following in your MCP config file under mcpServers:

{
  "mcpServers": {
    "tung-shing": {
      "command": "npx",
      "args": ["-y", "mcp-tung-shing@latest"]
    }
  }
}

4. Start or reload your MCP service manager to pick up the new server configuration. The exact command depends on your MCP environment, but typically looks like:

# If your MCP manager exposes a start/reload command:
pm run mcp-start

5. Test the endpoint by requesting data through your MCP client, using the get-tung-shing tool with parameters described in the README.

Tips and notes:

• The package name in the MCP config uses mcp-tung-shing; this aligns with the NPM package mcp-tung-shing published to npm.
• The default get-tung-shing operation returns one day of data; set days to fetch multiple days and includeHours to get hourly fortunes.
• If you plan to filter results, use tabooFilters with type 1 (宜) or 2 (忌) and specify the value(s) you want to include.
• When using npx to fetch the latest version, ensure your environment has network access to npm registry; network issues can prevent fetching the latest release.
• If you upgrade, verify compatibility with your MCP runtime and node version.
• If you encounter missing data for a given date, check for updates or issues in the upstream mcp-tung-shing package and consider pinning a specific version.