submit: Life Exchange Rate MCP (kongkoukk)

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/RIGHTS.md

@@ -0,0 +1,39 @@
+# Submission rights declaration
+
+Project: Life Exchange Rate MCP
+
+Submission slug: `kongkoukk-life-exchange-rate`
+
+Submitter: **kongkoukk**
+
+Date: **2026-09-16**
+
+GitHub account: [KongkouKK](https://github.com/KongkouKK)
+
+Public support contact: **haozlee1994@gmail.com**
+
+Source repository: https://github.com/KongkouKK/life-exchange-rate-mcp
+
+Review commit: `238954196ea6922d3cea2ae8acb914b0f4e01dbb`
+
+The submitter confirms that they own, or have sufficient authorization for, the source code, dependencies, service, data, branding, and other materials submitted in this pull request.
+
+Subject to the official program terms, the submitter authorizes X-Agent to retain, reproduce, audit, test, archive, and publish the submitted program artifact for judging, fraud prevention, dispute handling, ecosystem submission, and post-award accountability. Closing the pull request, deleting a fork, or deleting an external repository does not revoke the official archive rights attached to an accepted and rewarded entry.
+
+## First-party materials
+
+No general-purpose open-source license has been selected for the first-party project. The submitter grants the explicit submission, review, archive and related authorization stated above under the official program terms. This declaration does not assign MIT, Apache or another general-purpose license to first-party code.
+
+## Third-party components and data
+
+The [dependency inventory](verification/licenses/DEPENDENCIES.md) records the lockfile versions, inspected license metadata and evidence scope. [Original dependency notices](verification/licenses/THIRD_PARTY_NOTICES.txt) preserve the available upstream license, copyright and author texts. [Provider terms and supplementary upstream declarations](verification/licenses/PROVIDER-TERMS.md) record applicable source links, attribution requirements, exceptions and the limits of the inspection.
+
+The source uses ordinary dependencies through its manifests and lockfile. Generated dependency installations and build outputs are excluded from the review source. No blanket ownership over dependency implementations, upstream data, RSS text, names or marks is claimed.
+
+The implementation identifies Frankfurter's ECB reference-rate route, ECB structured policy-rate observations, Federal Reserve/ECB RSS, and optional EIA Brent observations. Their roles and data boundaries are documented in [data sources](source/docs/DATA_SOURCES.md). Preserve source attribution, observation dates and the distinction between provider observations, synthetic fixtures and project calculations.
+
+## Exceptions and restrictions
+
+Applicable third-party licenses, copyright notices, attribution requirements, provider terms and restrictions on third-party material or marks remain in force. The submission authorization does not replace those terms or grant rights the submitter cannot grant. The license and provider records identify their evidence limits, including the unverified exact isolated build-backend version; they are not a claim of unlimited rights over all upstream material.
+
+This declaration follows the [official program rights template](https://github.com/xagentAI/xagt-plugin/blob/main/submissions/RIGHTS_TEMPLATE.md) and was authorized by the submitter for this submission.

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/SUBMISSION.md

@@ -0,0 +1,78 @@
+# Life Exchange Rate MCP
+
+## Capability
+
+- **One-line description:** Translate structured macroeconomic changes into travel purchasing power, interest/fuel scenarios, work hours and user-defined everyday units.
+- **Who it helps:** Agents explaining a market move for a user who supplies income, prices, budgets and relevant exposures.
+- **Capability boundary:** Headlines trigger attention; numerical observations or labeled scenarios drive deterministic arithmetic. The service does not execute trades/payments, forecast prices, infer household income or claim that a separately retrieved headline caused a market move.
+
+## Live API
+
+- **API base URL:** https://life-exchange-rate-mcp.vercel.app
+- **Health check:** https://life-exchange-rate-mcp.vercel.app/health
+- **Deployment proof:** https://life-exchange-rate-mcp.vercel.app/.well-known/xagent-verification.json
+- **MCP endpoint:** https://life-exchange-rate-mcp.vercel.app/mcp/ — including the trailing slash.
+- **Authentication:** None for the public demonstration. No reviewer credential is required.
+- **Rate limits / known limits:** No application-level per-user quota is implemented. Free Vercel Hobby quotas, cold starts and upstream availability can affect service. The configured function duration is at most 30 seconds. MCP uses stateless HTTP/JSON; no availability guarantee or paid capacity is claimed.
+- **API contract:** [Live OpenAPI](https://life-exchange-rate-mcp.vercel.app/openapi.json), [checked-in OpenAPI](source/verification/openapi.json), [tool contracts](source/docs/TOOL_CONTRACTS.md).
+
+## Source and reproducibility
+
+- **Source repository:** https://github.com/KongkouKK/life-exchange-rate-mcp
+- **Review commit:** `238954196ea6922d3cea2ae8acb914b0f4e01dbb`
+- **Source submitted in this PR:** `source/`, including entry point, package files, fixtures, tests, `pyproject.toml`, `uv.lock` and configuration example.
+- **Source comparison:** The public archive's 76 files matched the prepared source with text line-ending differences ignored; no missing, differing or extra paths were found. See [source verification](verification/source-verification-final.json).
+
+From this submission directory, enter the runnable project and run:
+
+```bash
+cd source
+uv sync --locked --extra dev
+uv run --frozen python -m pytest
+uv run --frozen uvicorn life_exchange_rate.main:app --app-dir source --host 127.0.0.1 --port 8000
+```
+
+From that runnable project directory, the standalone protocol checks are:
+
+```bash
+uv run --frozen python verification/smoke_mcp.py
+uv run --frozen python verification/smoke_mcp.py --live-fx
+```
+
+Each smoke invocation starts and stops its own local server. The first uses fixtures; the second also requires live provider access.
+
+**Deploy:** Import the public source repository into Vercel Hobby, keeping the repository root, FastAPI framework, root `app.py` and the checked-in dependency lock. Keep system environment variables exposed. Use the public production domain; no protected-preview access is needed. See [deployment instructions](source/docs/DEPLOY_FREE.md). The build requirement names Hatchling without a pinned build-backend version; its exact isolated Vercel version has not been verified.
+
+**Version binding:** The app reads `VERCEL_GIT_COMMIT_SHA` and exposes it in both `/health` and the same-origin deployment proof. Both production endpoints were verified against the exact review commit above. A later source revision requires fresh version binding and verification before changing the review baseline.
+
+## Verification
+
+The project passed **148 local tests**. The hosted run at **2026-09-16 09:55:43 UTC** verified the declared review commit and passed:
+
+- Current protocol `2026-07-28` and legacy protocol `2025-11-25`: each listed **9 tools**, passed **12 positive calls** covering all nine tools and rejected **7 invalid-input cases**.
+- Live FX and official Fed RSS calls. Policy-rate and energy calls used clearly labeled synthetic fixtures; no live EIA test is claimed.
+- Synthetic FX calculation: **1,739.13 SEK / 8.70 work hours** at the declared synthetic household inputs.
+- Captured live FX calculation: source dates 2026-09-08 to 2026-09-15, rates 16.0689 to 15.8648 JPY/SEK; a synthetic 20,000 SEK budget produced **257.30 SEK / 1.29 work hours**. Later live observations can differ.
+
+The public REST run at **2026-09-16 10:00:54 UTC** returned HTTP 200 with the expected fixture values/provenance and HTTP 422 for invalid input, with the same commit before and after the calls.
+
+See the [repeatable verification runbook](verification/README.md), [complete hosted MCP record](verification/hosted-live-verification-final.json), [deterministic hosted record](verification/hosted-verification-final.json), and [REST record](verification/hosted-rest-verification-final.json).
+
+**Safe error behavior:** Invalid REST input returns HTTP 422; unavailable live providers return sanitized HTTP 502 responses. Invalid MCP calls return tool-error results. Policy/energy `live_or_fixture` mode can return an explicitly labeled synthetic fallback; `live` mode does not present such a fallback as a successful observation.
+
+These are application and deployment results. Official package validation is a separate pre-publication check; no unexecuted official check is represented as passed.
+
+## Security and data handling
+
+- **Data collected as request inputs:** Home currency/country, income, working hours, travel budget/currency, optional mortgage/savings/fuel exposures, everyday-unit prices, numeric events and pass-through assumptions.
+- **Purpose and retention:** Calculate the requested result. The application has no database or application-level persistence of household profiles. Vercel processes API traffic; hosting-layer request/log retention follows its settings, and no verified retention interval is asserted. Review profiles are synthetic.
+- **Outbound services:** Frankfurter's ECB FX route, ECB data API, Fed/ECB RSS, and EIA API when a key is configured. Providers receive currency/date/series queries, not the household income, mortgage or everyday-price profile.
+- **Secrets:** Optional `EIA_API_KEY` belongs only in the deployment environment. No credentials are included in this submission. No EIA key is needed for the synthetic judging flow.
+- **Known restrictions:** ECB daily reference rates are not executable retail quotes; retail fees/spreads are excluded. Interest/fuel pass-through is a stated scenario, with currency compatibility enforced. Free hosting and providers can be unavailable. [Provider terms](verification/licenses/PROVIDER-TERMS.md), attribution and third-party exceptions remain applicable.
+
+## Support
+
+- **Submitter:** kongkoukk
+- **GitHub:** [KongkouKK](https://github.com/KongkouKK)
+- **Public contact:** haozlee1994@gmail.com
+- **License / rights:** [RIGHTS.md](RIGHTS.md) records the submitter's authorized program review/archive/publishing declaration and preserves third-party terms. No general-purpose first-party open-source license has been selected.

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/source/.env.example

@@ -0,0 +1,8 @@
+# Local/self-hosted override. Vercel Git deployments use the actual platform SHA.
+REVIEW_COMMIT=dev-local
+SUBMISSION_SLUG=kongkoukk-life-exchange-rate
+# Leave unset on Vercel to use VERCEL_PROJECT_PRODUCTION_URL.
+# PUBLIC_BASE_URL=https://YOUR-VERIFIED-PRODUCTION-HOST
+FRANKFURTER_BASE_URL=https://api.frankfurter.dev
+# Optional; no key is needed for FX, ECB or fixture judging.
+EIA_API_KEY=

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/source/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.pyc
+.env
+.DS_Store
+
+.vercel/
+.env.*
+!.env.example
+dist/
+build/

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/source/.python-version

@@ -0,0 +1 @@
+3.12

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/source/.vercelignore

@@ -0,0 +1,10 @@
+.git
+.venv
+__pycache__
+.pytest_cache
+*.pyc
+tests
+docs
+verification
+.env
+.env.*

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/source/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.2.0 continuation
+
+- Installed and locked the current MCP SDK v2 dependencies; verified the `/mcp/` mount and scoped deployment hostname protection.
+- Added real-client Streamable HTTP smoke tooling for current and legacy protocols, including invalid input rejection.
+- Added calendar-correct live FX windows, preceding equal-horizon volatility scores and transparent history/zero-volatility fallbacks.
+- Added structured ECB policy-rate and EIA Brent adapters with replaceable HTTP transports, explicit synthetic fixtures and sanitized fallback behavior.
+- Preserved event provenance in impact results; corrected inverse-FX trace units, percent factors and foreign-mortgage currency handling.
+- Enforced finite numeric inputs, consistent price changes, timestamp zones and scenario labels; exposed pass-through assumptions over MCP.
+- Fixed demo dates and labels; added a complete event/radar/travel/work/life-unit demo, checked OpenAPI and verification fixtures.
+
+Public deployment and review Git SHA remain pending real submission configuration.

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/source/DEPLOYMENT_STATUS.md

@@ -0,0 +1,26 @@
+# Deployment status
+
+Updated 2026-09-16. The application is publicly deployed for GitHub account KongkouKK on Vercel Hobby, for a personal, noncommercial demonstration.
+
+- Source repository: [KongkouKK/life-exchange-rate-mcp](https://github.com/KongkouKK/life-exchange-rate-mcp).
+- Production origin: [life-exchange-rate-mcp.vercel.app](https://life-exchange-rate-mcp.vercel.app).
+- [API documentation](https://life-exchange-rate-mcp.vercel.app/docs), [health](https://life-exchange-rate-mcp.vercel.app/health), and [deployment proof](https://life-exchange-rate-mcp.vercel.app/.well-known/xagent-verification.json) were checked successfully. Use the proof or health response to read the currently deployed Git revision; a documentation commit is not the deployment's source of truth.
+- Canonical MCP endpoint: `https://life-exchange-rate-mcp.vercel.app/mcp/`. Current and legacy protocol initialization passed, and both modes listed and called all nine tools.
+
+## Verification completed
+
+The application and three deployment configuration checks passed together: **148 local tests**. The earlier `verification/summary.json` and `build-check.json` describe the original local stage (145 tests and its wheel); they remain historical evidence, not proof of a Vercel build.
+
+The complete hosted run at **2026-09-16 06:40 UTC** passed protocol versions `2026-07-28` and `2025-11-25`. Each mode listed all nine tools, made 12 successful calls covering every tool, and rejected seven invalid inputs: unsupported event mode, unknown headline source, identical FX currencies, out-of-range lookback, a headline lacking numeric event values, conversion currency mismatch, and an invalid scenario multiplier.
+
+Live ECB/Frankfurter FX observations and Fed RSS were fetched successfully. Policy-rate and energy tools used synthetic fixtures; this is not evidence of hosted live policy-rate or EIA calls. The observed FX chain covered event retrieval → ranking → personal impact → life-unit conversion. Rates changed from 16.0689 to 15.8648 JPY/SEK between September 8 and 15; the explicit synthetic 20,000 SEK travel profile needed **257.30 SEK / 1.29 work hours** to restore its earlier JPY purchasing power. The separately fetched Fed headline was not asserted to cause the move.
+
+The [saved hosted run](verification/hosted-live-2026-09-16.json) includes health/proof responses before and after the calls, with the same expected source revision and production origin throughout. It is a historical record bound to the revision inside that JSON. Query the public deployment proof for the current revision, and capture fresh evidence when reviewing a later deployment.
+
+An earlier hosted fixture run at 06:30 UTC used MCP SDK 2.2.0 and returned the fixed result **1,739.13 SEK / 8.70 work hours**. Its health request returned HTTP 200 in 406 ms and deployment proof returned HTTP 200 in 297 ms, without redirects and within a 10-second request timeout. The source revision matched the expected deployed revision, and proof origin, slug, and MCP URL matched the production configuration. These are measurements of that run, not a guarantee of future latency or cold-start behavior.
+
+## Free plan and remaining submission work
+
+Vercel Hobby is the selected free plan, subject to its personal/noncommercial terms and quotas. No paid upgrade is required for this demonstration. No EIA key is configured, so energy results use an explicitly labeled synthetic scenario fallback; live EIA validation remains unperformed. See [free deployment instructions](docs/DEPLOY_FREE.md).
+
+Deployment does not complete contest submission. `submission.json` and `SUBMISSION.md` still need final review against the deployed proof, and `RIGHTS.md` requires the submitter's declarations. **No official contest pull request has been submitted.**

submissions/mcp-hackathon/kongkoukk-life-exchange-rate/source/Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.13-slim
+WORKDIR /app
+RUN pip install --no-cache-dir uv==0.12.13
+COPY pyproject.toml uv.lock ./
+COPY source ./source
+RUN uv sync --locked --no-dev --no-editable
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PORT=8000
+CMD ["sh", "-c", "uvicorn life_exchange_rate.main:app --host 0.0.0.0 --port ${PORT:-8000}"]