portfolio-analytics-mcp 0.2.0__tar.gz

portfolio_analytics_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Cancel superseded runs of the same branch/PR.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci-checks:
+    name: CI checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      # Python version comes from .python-version (kept in sync with
+      # PYTHON_VERSION in render.yaml).
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      # Same command as locally: format-check (ruff + prettier), lint,
+      # type check and tests with the coverage minimum.
+      - run: uv run poe ci-checks
+      - name: Build package
+        run: uv build

portfolio_analytics_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+# Pushing a tag like v1.2.3 runs the checks, builds version 1.2.3 (taken from
+# the tag by hatch-vcs) and publishes it to PyPI.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Check and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0 # full history and tags, so hatch-vcs sees the tag
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+      - run: uv sync --locked
+      - run: uv run poe ci-checks
+      - run: uv build
+      # Guard against a tag on the wrong commit or an unexpected version.
+      - name: Check version matches tag
+        run: |
+          expected="$(uv run --with packaging python -c \
+            'from packaging.version import Version; import sys; print(Version(sys.argv[1]))' \
+            "${GITHUB_REF_NAME#v}")"
+          ls dist
+          test -f "dist/portfolio_analytics_mcp-${expected}-py3-none-any.whl" \
+            || { echo "Built version does not match tag ${GITHUB_REF_NAME}"; exit 1; }
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/portfolio-analytics-mcp/
+    permissions:
+      id-token: write # trusted publishing: PyPI accepts this job's identity, no token stored
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+      - run: uv publish --trusted-publishing always

portfolio_analytics_mcp-0.2.0/.gitignore

@@ -0,0 +1,64 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDEs
+.idea/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# macOS
+.DS_Store
+
+# Local tooling
+.vscode/
+.ruff_cache/

portfolio_analytics_mcp-0.2.0/.python-version

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

portfolio_analytics_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing
+
+Thanks for your interest! Bug reports, fixes and new tools are welcome.
+Please open an issue first for larger changes, so we can agree on the
+approach.
+
+## Setup
+
+You need [uv](https://docs.astral.sh/uv/) and Python 3.12. Formatting
+Markdown and YAML also needs [Node.js](https://nodejs.org) (Prettier runs
+through `npx`, nothing to install).
+
+```bash
+git clone https://github.com/RugSec/portfolio-analytics-mcp.git
+cd portfolio-analytics-mcp
+uv sync                     # creates .venv with runtime + dev dependencies
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+```
+
+## Tasks
+
+Tasks run with [poe](https://poethepoet.natn.io/) (`poe -h` lists them):
+
+| Command            | What it does                                                       |
+| ------------------ | ------------------------------------------------------------------ |
+| `poe ci-checks`    | Everything CI runs, read-only: format-check, lint, typecheck, test |
+| `poe test`         | Tests with coverage; fails below 80%                               |
+| `poe format`       | Format Python (ruff) and Markdown/YAML (Prettier), sort imports    |
+| `poe fix`          | Format, then lint                                                  |
+| `poe format-check` | Check formatting without writing files                             |
+| `poe lint`         | Lint with ruff (style, docstrings, type hints)                     |
+| `poe typecheck`    | Type check with basedpyright                                       |
+| `poe check`        | Quick check: lint + typecheck                                      |
+
+**Run `poe ci-checks` before opening a pull request.** GitHub Actions runs
+the same command on Python 3.12.
+
+To try the tools interactively, use the MCP inspector:
+`mcp dev finance_mcp/server.py`. To check that Yahoo is reachable from your
+machine:
+
+```bash
+uv run python -c "from finance_mcp.yahoo.tools import get_quote; print(get_quote(['AAPL']))"
+```
+
+## Project layout
+
+```
+finance_mcp/
+  server.py          builds the FastMCP server and registers all tools
+  auth.py            API-key middleware for the HTTP transport
+  yahoo/
+    analytics.py     return/risk maths: pure pandas/numpy, no network
+    data.py          yfinance downloads, currencies, FX, error classification
+    tools.py         Yahoo MCP tools
+  justetf/
+    client.py        polite HTTP: rate limit, retries, disk cache, ISIN check
+    parser.py        profile page HTML -> dict (stable data-testid hooks)
+    service.py       fetch + parse + cache, the tools' single entry point
+    registry.py      local name/ticker -> ISIN registry (seed + learned)
+    search.py        ETF search: ISIN, registry, then Yahoo fallback
+    analysis.py      ETF portfolio maths: pure functions, no network
+    tools.py         justETF MCP tools
+    data/etfs.json   seed registry of popular ETFs
+  portfolio/
+    resolve.py       ISIN -> Yahoo symbols via justETF listings
+    risk.py          whole-portfolio risk in one base currency
+    tools.py         portfolio MCP tools
+tests/               mirrors finance_mcp/ (tests/yahoo, tests/justetf, ...)
+  conftest.py        fixtures that fake Yahoo and justETF
+  fakes.py           synthetic prices, pages and profiles
+```
+
+The pattern in each package: network code (`data.py`, `client.py`) is
+separate from pure logic (`analytics.py`, `parser.py`, `analysis.py`), and
+`tools.py` only adapts inputs and outputs for the MCP client.
+
+## Conventions
+
+- **Tests never touch the network.** Fake Yahoo and justETF with the
+  fixtures in `tests/conftest.py` (`fake_yahoo`, `fake_yf`, `registry_env`)
+  or with `monkeypatch`. Put a module's tests in the matching file under
+  `tests/`, e.g. `finance_mcp/justetf/parser.py` in
+  `tests/justetf/test_parser.py`.
+- **Coverage stays at or above 80%** (branch coverage); CI fails below it.
+- **Type hints on every function**, checked by basedpyright.
+- **Docstrings on every function** in Google style: a one-line summary, then
+  `Args:`, `Returns:` and `Raises:` sections as they apply. Test functions
+  only need the one-line summary. Ruff enforces this.
+- **Tool docstrings are read by the LLM.** They are the tool's description,
+  so say when to use the tool, what it needs and what comes back, and keep
+  them short.
+- **Tools return errors, they don't raise them.** Return
+  `YahooError(...).to_dict()` (with an `error_code` from the
+  [user guide](docs/USER_GUIDE.md#errors)) or `{"error": ...}`, so the agent
+  can explain the failure or try another tool.
+- **Be polite to data sources.** New justETF requests go through
+  `client._get` (rate limit + retries) and the cache; never retry a 403/429.
+
+## Dependencies
+
+Dependencies are declared in `pyproject.toml` and locked in `uv.lock`.
+
+- `mcp` is pinned below 2 because the code uses the v1 `FastMCP` API.
+- `pandas` is pinned exactly, with a matching `pandas-stubs` in the dev
+  group: bump both together.
+- Dependabot opens monthly update PRs for Python packages and GitHub
+  Actions.
+
+## Releases
+
+The version comes from the git tag ([hatch-vcs](https://github.com/ofek/hatch-vcs)),
+so there is no version number to edit in `pyproject.toml`. To release from an
+up-to-date `main`:
+
+```bash
+git tag -a v0.2.0 -m "v0.2.0"
+git push origin v0.2.0
+```
+
+The [Release workflow](.github/workflows/release.yml) runs `poe ci-checks`,
+builds the package, checks that its version matches the tag and publishes it
+to [PyPI](https://pypi.org/project/portfolio-analytics-mcp/) with trusted
+publishing (no token stored). Users running `uvx portfolio-analytics-mcp@latest`
+get it the next time the server starts.
+
+- Use [semantic versioning](https://semver.org): patch for fixes, minor for
+  new tools or fields, major for removed or renamed tools.
+- PyPI never accepts the same version twice, even after deleting it. Fix a
+  bad release by tagging the next patch version.
+- Builds between tags get a development version such as
+  `0.2.1.dev3+g1a2b3c4`; PyPI rejects these, so only tags can be published.
+- `skill/portfolio-analytics/SKILL.md` has its own `version`: bump it only
+  when you change the skill and upload it to Agensi again.

portfolio_analytics_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruggiero Seccia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

portfolio_analytics_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: portfolio-analytics-mcp
+Version: 0.2.0
+Summary: MCP server for portfolio analysis with Yahoo Finance and justETF data
+Project-URL: Homepage, https://github.com/RugSec/portfolio-analytics-mcp
+Project-URL: Documentation, https://github.com/RugSec/portfolio-analytics-mcp/blob/main/docs/USER_GUIDE.md
+Project-URL: Issues, https://github.com/RugSec/portfolio-analytics-mcp/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: etf,finance,investing,justetf,mcp,portfolio,yfinance
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: ==3.12.*
+Requires-Dist: beautifulsoup4>=4.15.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]<2,>=1.9.0
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas==3.0.6
+Requires-Dist: pydantic>=2.7
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: yfinance>=0.2.50
+Description-Content-Type: text/markdown
+
+# Portfolio Analytics MCP
+
+[![PyPI](https://img.shields.io/pypi/v/portfolio-analytics-mcp.svg)](https://pypi.org/project/portfolio-analytics-mcp/)
+[![CI](https://github.com/RugSec/portfolio-analytics-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/RugSec/portfolio-analytics-mcp/actions/workflows/ci.yml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/LICENSE)
+
+**Ask Claude about your investments in plain language.** This is an
+[MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP
+client) read-only tools for market data and portfolio analysis: prices, FX,
+ETF costs and exposure, and risk for a whole portfolio of stocks and ETFs,
+measured in your own currency.
+
+It is built for European investors as much as US ones: it understands ISINs,
+UCITS ETFs listed on several exchanges, and prices quoted in pence.
+
+## What you can ask
+
+> "I hold 30k EUR of IE00B4L5Y983, 10 ASML.AS and 25 AAPL. How volatile is
+> this portfolio, and which position contributes most to the risk?"
+
+> "Compare the costs of the iShares Core MSCI World and the Vanguard FTSE
+> All-World. Which is cheaper and bigger?"
+
+> "How much of my ETF portfolio is in US tech stocks? Do my ETFs overlap?"
+
+> "What has VWCE returned since 2021 in euros, compared with the S&P 500?"
+
+Claude picks the right tools, fetches the data and explains the result.
+
+## What's inside
+
+| Area          | What it gives you                                                                                      | Data source                                |
+| ------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| **Portfolio** | Risk and return of a mixed portfolio in one currency: volatility, drawdown, beta, risk per position    | Yahoo Finance + justETF                    |
+| **ETFs**      | Costs (TER), fund size, country/sector/stock exposure, listings, similar funds, portfolio look-through | [justETF](https://www.justetf.com)         |
+| **Markets**   | Price history, quotes, FX rates, performance statistics, correlations, dividends                       | [Yahoo Finance](https://finance.yahoo.com) |
+
+20 tools in total, all read-only. No API key or account needed. See the
+[user guide](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/docs/USER_GUIDE.md) for the full list.
+
+## Quickstart
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/). It
+downloads Python 3.12, the server and its dependencies on first run, and
+checks for a new release each time the server starts.
+
+**1. Connect it to Claude**
+
+Claude Code:
+
+```bash
+claude mcp add finance -- uvx portfolio-analytics-mcp@latest
+```
+
+Claude Desktop: add this to `claude_desktop_config.json`, then restart the
+app. If it can't find `uvx`, use the full path that `which uvx` prints.
+
+```json
+{
+  "mcpServers": {
+    "finance": {
+      "command": "uvx",
+      "args": ["portfolio-analytics-mcp@latest"]
+    }
+  }
+}
+```
+
+To stay on one version instead, use `portfolio-analytics-mcp==0.2.0`.
+
+The server runs on your machine. Only symbols and ISINs go out, to Yahoo
+Finance and justETF; your quantities and amounts never leave it.
+
+**2. Ask a question**, for example _"What is the TER of IE00B4L5Y983?"_
+
+To work on the code instead, see [Contributing](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/CONTRIBUTING.md#setup).
+
+Want to run it as a shared remote server instead? See
+[Remote deployment](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/docs/USER_GUIDE.md#remote-deployment-http).
+
+## Important to know
+
+- **Not financial advice.** The tools report data and statistics; past
+  performance does not predict future results. Data can be delayed,
+  incomplete or wrong, and is provided as is, without warranty.
+- **Not affiliated** with Yahoo, justETF or any fund provider. Names and
+  trademarks belong to their owners.
+- **Personal use only.** Yahoo Finance (through the unofficial
+  [yfinance](https://pypi.org/project/yfinance/) library) and justETF are
+  third-party sites. This server makes polite, on-demand requests
+  (rate-limited and cached) and is not meant for bulk downloads or
+  redistributing their data. Check their terms before using it.
+- Quotes can be delayed by up to ~20 minutes, and Yahoo's coverage of
+  European ETF holdings is patchy (the justETF tools fill that gap).
+
+## Learn more
+
+- [User guide](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/docs/USER_GUIDE.md): every tool, example workflows,
+  configuration, remote deployment and limitations.
+- [Agent skill](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/skill/portfolio-analytics/SKILL.md): tells an agent when
+  and how to use the tools, and how to present results.
+- [Contributing](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/CONTRIBUTING.md): development setup, tests and project
+  layout.
+
+## License
+
+[MIT](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/LICENSE)

portfolio_analytics_mcp-0.2.0/README.md

@@ -0,0 +1,108 @@
+# Portfolio Analytics MCP
+
+[![PyPI](https://img.shields.io/pypi/v/portfolio-analytics-mcp.svg)](https://pypi.org/project/portfolio-analytics-mcp/)
+[![CI](https://github.com/RugSec/portfolio-analytics-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/RugSec/portfolio-analytics-mcp/actions/workflows/ci.yml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/LICENSE)
+
+**Ask Claude about your investments in plain language.** This is an
+[MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP
+client) read-only tools for market data and portfolio analysis: prices, FX,
+ETF costs and exposure, and risk for a whole portfolio of stocks and ETFs,
+measured in your own currency.
+
+It is built for European investors as much as US ones: it understands ISINs,
+UCITS ETFs listed on several exchanges, and prices quoted in pence.
+
+## What you can ask
+
+> "I hold 30k EUR of IE00B4L5Y983, 10 ASML.AS and 25 AAPL. How volatile is
+> this portfolio, and which position contributes most to the risk?"
+
+> "Compare the costs of the iShares Core MSCI World and the Vanguard FTSE
+> All-World. Which is cheaper and bigger?"
+
+> "How much of my ETF portfolio is in US tech stocks? Do my ETFs overlap?"
+
+> "What has VWCE returned since 2021 in euros, compared with the S&P 500?"
+
+Claude picks the right tools, fetches the data and explains the result.
+
+## What's inside
+
+| Area          | What it gives you                                                                                      | Data source                                |
+| ------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
+| **Portfolio** | Risk and return of a mixed portfolio in one currency: volatility, drawdown, beta, risk per position    | Yahoo Finance + justETF                    |
+| **ETFs**      | Costs (TER), fund size, country/sector/stock exposure, listings, similar funds, portfolio look-through | [justETF](https://www.justetf.com)         |
+| **Markets**   | Price history, quotes, FX rates, performance statistics, correlations, dividends                       | [Yahoo Finance](https://finance.yahoo.com) |
+
+20 tools in total, all read-only. No API key or account needed. See the
+[user guide](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/docs/USER_GUIDE.md) for the full list.
+
+## Quickstart
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/). It
+downloads Python 3.12, the server and its dependencies on first run, and
+checks for a new release each time the server starts.
+
+**1. Connect it to Claude**
+
+Claude Code:
+
+```bash
+claude mcp add finance -- uvx portfolio-analytics-mcp@latest
+```
+
+Claude Desktop: add this to `claude_desktop_config.json`, then restart the
+app. If it can't find `uvx`, use the full path that `which uvx` prints.
+
+```json
+{
+  "mcpServers": {
+    "finance": {
+      "command": "uvx",
+      "args": ["portfolio-analytics-mcp@latest"]
+    }
+  }
+}
+```
+
+To stay on one version instead, use `portfolio-analytics-mcp==0.2.0`.
+
+The server runs on your machine. Only symbols and ISINs go out, to Yahoo
+Finance and justETF; your quantities and amounts never leave it.
+
+**2. Ask a question**, for example _"What is the TER of IE00B4L5Y983?"_
+
+To work on the code instead, see [Contributing](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/CONTRIBUTING.md#setup).
+
+Want to run it as a shared remote server instead? See
+[Remote deployment](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/docs/USER_GUIDE.md#remote-deployment-http).
+
+## Important to know
+
+- **Not financial advice.** The tools report data and statistics; past
+  performance does not predict future results. Data can be delayed,
+  incomplete or wrong, and is provided as is, without warranty.
+- **Not affiliated** with Yahoo, justETF or any fund provider. Names and
+  trademarks belong to their owners.
+- **Personal use only.** Yahoo Finance (through the unofficial
+  [yfinance](https://pypi.org/project/yfinance/) library) and justETF are
+  third-party sites. This server makes polite, on-demand requests
+  (rate-limited and cached) and is not meant for bulk downloads or
+  redistributing their data. Check their terms before using it.
+- Quotes can be delayed by up to ~20 minutes, and Yahoo's coverage of
+  European ETF holdings is patchy (the justETF tools fill that gap).
+
+## Learn more
+
+- [User guide](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/docs/USER_GUIDE.md): every tool, example workflows,
+  configuration, remote deployment and limitations.
+- [Agent skill](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/skill/portfolio-analytics/SKILL.md): tells an agent when
+  and how to use the tools, and how to present results.
+- [Contributing](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/CONTRIBUTING.md): development setup, tests and project
+  layout.
+
+## License
+
+[MIT](https://github.com/RugSec/portfolio-analytics-mcp/blob/main/LICENSE)