AGENTS.md — myfund-mcp

AI agent guidance for this repository. Read this before making changes.

What This Project Does

myfund-mcp is a Rust MCP (Model Context Protocol) server that exposes investment portfolio data from myfund.pl as MCP tools. It is intended to be used with Claude Desktop, GitHub Copilot, or any MCP-compatible AI assistant.

Project Structure

myfund-mcp/
├── AGENTS.md           ← you are here
├── Cargo.toml          ← dependencies (rmcp, tokio, reqwest, serde, anyhow, tracing, wiremock dev)
├── README.md           ← user-facing setup and config instructions
├── tests/
│   └── fixtures/
│       ├── portfolio_ok.json     ← realistic success response (3 tickers, all time-series)
│       └── portfolio_error.json  ← API error response (status.code = "1")
└── src/
    ├── main.rs         ← entry point: reads env vars, sets up tracing, starts stdio transport
    ├── server.rs       ← MCP ServerHandler with #[tool] macro implementations + unit tests
    ├── myfund.rs       ← HTTP client for the myfund.pl API + unit tests
    └── models.rs       ← serde data models for myfund.pl JSON responses + unit tests

Architecture

stdin/stdout (MCP stdio)
       │
       ▼
  main.rs  ──── reads MYFUND_API_KEY, MYFUND_PORTFOLIOS env vars
       │         starts rmcp stdio transport
       ▼
  server.rs  ── ServerHandler impl
       │         three #[tool] methods (see below)
       ▼
  myfund.rs  ── MyfundClient
       │         single async fn: fetch_portfolio(name) → PortfolioResponse
       ▼
  myfund.pl API (HTTPS, API key auth via query param)

Tracing/logging goes to stderr only — stdout is reserved for the MCP stdio channel.

MCP Tools

Valid series values for get_portfolio_timeseries:

• wartoscWCzasie — daily portfolio value
• zyskWCzasie — daily profit
• wkladWCzasie — daily own contribution
• benchWCzasie — benchmark return
• stopaZwrotuWCzasie — portfolio rate of return

myfund.pl API

• Endpoint: GET https://myfund.pl/API/v1/getPortfel.php?portfel={name}&apiKey={key}&format=json
• Auth: API key passed as query param (no sessions, no cookies)
• Response size: ~660 KB (includes full daily time-series since portfolio inception)
• Server-side cache: 5 minutes (repeated requests within 5 min return the same data)
• Error response: {"status":{"code":"1","text":"<message>"}}
• Portfolio names are case-sensitive

Response JSON Shape

status              { code: "0"|"1", text: string }
portfel             { benchName, tickersCount, nazwa, waluta, wartosc, zysk, zyskDzienny,
                      zmianaDzienna, close, liczbaJednostek, udzial, zmiana,
                      zmianaW, zmiana2W, zmianaM, zmiana3M, zmiana6M, zmianaR,
                      zmiana3R, zmiana5R, zmianaMdD, zmianaRdD, ... }
                    NOTE: mixed types — some fields are f64, some are String
tickers             HashMap<numeric_string_id, Ticker>
                    Ticker: { tickerClear, nazwa, data, close, zmianaDzienna,
                              liczbaJednostek, typ, typOrg, wartosc, udzial, zmiana,
                              cenaZakupu, zysk, kontoInvName, sektor, ryzyko,
                              portfelOrg, dataInvStart, okresInwestycji }
                    NOTE: all Ticker fields are strings
struktura           HashMap<asset_type_name, value_string>
strukturaWalory     HashMap<ticker_name, share_string>
strukturaKolor, strukturaWaloryKolor  (color maps, can be ignored)
wartoscWCzasie      HashMap<"YYYY-MM-DD", value_string>
zyskWCzasie         HashMap<"YYYY-MM-DD", value_string>
wkladWCzasie        HashMap<"YYYY-MM-DD", value_string>
benchWCzasie        HashMap<"YYYY-MM-DD", value_string>
stopaZwrotuWCzasie  HashMap<"YYYY-MM-DD", value_string>
zmianaDzienna       HashMap<"YYYY-MM-DD", value_string>  (usually just today)

Test Fixtures

Located in tests/fixtures/:

Load in tests with: include_str!("../tests/fixtures/portfolio_ok.json")

Unit Test Summary (30 tests across 3 modules)

• models.rs (12 tests): deserialization of both fixtures, field value assertions, ticker count/fields, struktura keys, time-series entries, is_error() helper
• myfund.rs (6 tests): HTTP mock tests with wiremock — success path, API error propagation, HTTP 500, query param correctness
• server.rs (12 tests): tool output content (portfel/tickers present, time-series absent in summary), date range filtering (from, range, empty), invalid series name, error propagation, list_portfolios with/without env var

Key Dependencies

Configuration

The server exits with a clear error message if MYFUND_API_KEY is not set.

Coding Conventions

• Use anyhow::Result for error propagation throughout.
• Tool methods on MyfundServer use the #[tool] proc-macro from rmcp-macros.
• serde_json::Value is used for the portfel summary fields due to mixed types in the API response.
• All Ticker struct fields are Option<String> to handle missing fields gracefully.
• Time-series types are HashMap<String, String> (date → value).
• Do not add client-side caching — the myfund.pl API already caches for 5 minutes.
• Do not write to stdout from application code — it breaks the MCP stdio channel.