# Agentic Player 10 Saju MCP

## Context

- Contest: Kakao Agentic Player 10
- Target platform: PlayMCP / Kakao Tools
- Selected idea: fortune / astrology context MCP based on saju, zi wei dou shu, and western astrology.
- Current strategy: win preliminary review with a simple, no-storage, text-first MCP that fits KakaoTalk-style personal conversations.

## SSOT Documents

- [Contest and Platform SSOT](docs/contest-ssot.md): contest rules, PlayMCP constraints, deployment assumptions, and open questions.
- [Product Decision](docs/product-decision.md): why the project is now focused on the saju MCP instead of the MCP discovery MCP.
- [Feasibility Review](feasibility.md): implementation feasibility notes for both candidate ideas.
- [Testing and Deployment](docs/testing-and-deployment.md): local checks, Docker build, PlayMCP temporary registration, and KakaoTalk/Kakao Tools testing path.
- [Kakao Profile Data](docs/kakao-profile-data.md): whether birth date and gender can be supplied from a Kakao account.
- [Submission Readiness](docs/submission-readiness.md): current preliminary-review checklist, evidence, and remaining blockers.

## Confirmed Constraints

- PlayMCP in KC is required for preliminary submission.
- Deployment options are Git source build or container image.
- Remote MCP over Streamable HTTP is required.
- Stateless MCP is recommended.
- PlayMCP AI chat primarily expects TextContent responses.
- Preliminary MVP should not store user personal data.
- User personalization and saved profiles are reserved for finals or later versions.
- Recommended tool count is 3 to 10, with a hard cap at 20. The MVP intentionally starts with one high-value tool.

## Selected Idea

Build a personal counseling MCP that answers user concerns through:

- Saju / Four Pillars
- Zi Wei Dou Shu
- Western astrology birth chart

For the preliminary MVP, the product does not store the user's birth profile. The user provides birth information inside each tool call or conversation, and the server computes one AI-friendly context pack.

The MCP calculates Saju, Zi Wei Dou Shu, and Western natal chart facts locally. It turns the structured calculation into short, question-scoped fact cards. The deployed preliminary build gives those cards to Cerebras `gpt-oss-120b` with a 2.5-second deadline and a 900-token completion budget. A provider error, timeout, or ungrounded output falls back to chart-specific interpretation rules plus verified facts so the host AI can finish the answer without losing the calculation.

Saved profiles, reminders, and repeat-visit personalization are finalist or later-version features.

## Product Principle

This is not positioned as deterministic prediction. It should feel like reflective entertainment and structured self-counseling.

Strengths:

- Easy MVP.
- No auth, DB, or profile persistence required for preliminary review.
- Broad KakaoTalk audience fit.
- Text-only PlayMCP output is enough.
- Can expand into charts, monthly reports, compatibility, and widgets later.

Main risk:

- Birth data is sensitive, so the preliminary MVP avoids storage and keeps careful answer wording from the start.

## Current MVP

The implemented MCP exposes one tool:

```text
generate_fortune_context
```

It accepts one-time birth information plus the user's current question and returns one Markdown response containing either:

- A complete user-facing counseling answer generated by Cerebras `gpt-oss-120b`.
- Or chart-specific interpretation guidance plus deterministic, question-scoped facts.

The external LLM request excludes the raw birth date/time, birthplace, coordinates, input summary, and full chart dump. It sends only the user's current question and deterministic fact cards needed for that question. Those facts can still permit indirect inference, so the service does not claim that the payload is fully anonymous.

The MCP does not receive Kakao account profile fields automatically. The preliminary version therefore asks for birth date, time, gender, and birthplace in the conversation and does not persist them.

## Workers AI

Create a Workers AI API token with only Workers AI read/edit access, then configure:

```bash
cp .env.example .env
```

Required variables:

- `CLOUDFLARE_ACCOUNT_ID`
- `CLOUDFLARE_API_TOKEN`

Optional variables:

- `CLOUDFLARE_AI_MODEL` (default: `@cf/google/gemma-4-26b-a4b-it`)
- `CLOUDFLARE_AI_TIMEOUT_MS` (default: `60000`)
- `CLOUDFLARE_AI_MAX_TOKENS` (default: `600`)

The hybrid benchmark runs five full reading calls and validates both the generated-answer and guided-fallback routes:

```bash
npm run benchmark:reading
```

On 2026-07-12, three five-call runs at the former 2.5-second deadline measured 2,460-2,554ms maximum and 2,219-2,447ms average, with one or two grounded Gemma answers per run and guided fallbacks for the remainder. Later checks varied from a 2,570ms truncated completion to repeated timeouts beyond 30 seconds. With the 600-token budget, one grounded complete reading finished in 19,334ms. The product decision now favors waiting up to 60 seconds with the larger completion budget. PlayMCP already shows a generic `TOOL call / loading` state while the call is pending, but its public client does not expose custom MCP progress stages. This quality-first timeout does not satisfy PlayMCP's documented average 100ms and mandatory p99 3,000ms guidance, so it must be treated as a submission risk rather than a performance-compliant configuration.

Current deployment: `https://fortune-reading-mcp-v4.playmcp-endpoint.kakaocloud.io/mcp` (`fortune-reading-mcp-v4`, ID `2889`, Active).

Do not commit `.env` or put the API token in the Docker image. Use PlayMCP in KC deployment secrets.

## Cerebras Deployment

The deployed preliminary build uses Cerebras `gpt-oss-120b` only for final-answer wording; the deterministic calculation, fact cards, and grounding checks remain local and unchanged. Cloudflare Workers AI remains an explicit optional adapter for comparison and fallback development, not the current deployment provider.

Local variables:

- `CEREBRAS_API_KEY`
- `CEREBRAS_AI_MODEL` (default: `gpt-oss-120b`)
- `CEREBRAS_AI_TIMEOUT_MS` (default: `2500`)
- `CEREBRAS_AI_MAX_TOKENS` (default: `900`)

Run the free-tier-aware benchmark with at least 12 seconds between calls:

```bash
npm run benchmark:reading:cerebras -- gpt-oss-120b 3000 2500 5 12500
```

On 2026-07-12, the final five-call run produced five grounded complete readings with 749ms average and 860ms maximum latency. A three-scenario run covering Saju, Zi Wei Dou Shu, and Western astrology produced three grounded complete readings with 726ms average and 750ms maximum latency. The account's displayed free quota is five requests per minute, 150 per hour, 2,400 per day, and one million tokens per day. This clears PlayMCP's 3,000ms p99 boundary in the measured samples but not its separate 100ms average target.

The v0.3.1 endpoint returned MCP initialize in 490ms, `tools/list` in 174ms, and a complete default reading in 1,170ms. The output included the final consultation, plain-language explanations, and an expert-evidence section. PlayMCP information loading, the existing draft update, and the two-turn AI Chat flow all passed against v4. The previous v3 server was deleted after those checks, so only one KakaoCloud MCP server remains.

The contest preliminary build intentionally uses the Cerebras free plan to keep the validation MVP simple and cost-free. Its five-request-per-minute quota is suitable only for judging, demos, and low-volume testing; it is not presented as production capacity. If the project advances to public Kakao Tools voting or receives real user traffic, the operator must move to paid inference capacity before public exposure. End users are never asked to purchase or configure an LLM account.

`ALLOWED_ORIGINS` is a comma-separated allowlist for browser-originated MCP requests. It defaults to `https://playmcp.kakao.com`; requests without an `Origin` header remain supported for server-to-server MCP clients.

## Local Commands

```bash
npm install
npm test
npm run build
HOST=127.0.0.1 PORT=3333 npm start
```

## License and Attribution

This project is licensed under AGPL-3.0-only.

The calculation core uses [`@orrery/core`](https://github.com/rath/orrery), also licensed under AGPL-3.0-only. Orrery provides the browser-first Saju, Zi Wei Dou Shu, and Western natal chart calculation logic that this MCP formats into an AI-readable context pack.

The corresponding source for the deployed service is this public repository. The project does not claim ownership of Orrery's calculation algorithms or upstream third-party packages.