Metadata-Version: 2.5
Name: studio-saelix-finance
Version: 0.1.0
Summary: Read-only Studio Saelix Finance MCP server for Plaid-connected accounts.
Project-URL: Homepage, https://github.com/Studio-Saelix/finance-mcp
Project-URL: Repository, https://github.com/Studio-Saelix/finance-mcp
Project-URL: Issues, https://github.com/Studio-Saelix/finance-mcp/issues
Author: Studio Saelix
License: MIT
License-File: LICENSE
Keywords: chatgpt,claude,finance,fintech,llm,mcp,plaid
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=43.0
Requires-Dist: fastmcp>=2.2.0
Requires-Dist: plaid-python>=36.0.0
Requires-Dist: pydantic>=2.6
Requires-Dist: tomli>=2; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Studio Saelix Finance MCP

Studio Saelix Finance MCP is a stdio-only, read-only MCP server for Plaid-connected financial data.

The runtime exposes exactly these tools:

- `list_accounts`
- `get_balances`
- `sync_transactions`
- `refresh_transactions`
- `get_transactions`
- `search_transactions`
- `spending_summary`
- `get_holdings`
- `get_investment_transactions`
- `get_liabilities`

Runtime writes are limited to retrieval cache maintenance: account and transaction cache rows, transaction cursors, and sanitized retrieval errors. The runtime cannot enroll or unlink institutions, exchange tokens, manage credentials, mutate user-maintained debt data, execute payments, or use remote HTTP transport.

## Administrator setup

The normal installation does not require a repository checkout or a manually
managed virtual environment. `uvx` creates an isolated environment for each
tool invocation:

```bash
uvx --from 'studio-saelix-finance==0.1.0' studio-saelix-finance init
uvx --from 'studio-saelix-finance==0.1.0' studio-saelix-finance link
uvx --from 'studio-saelix-finance==0.1.0' studio-saelix-finance status
```

On a new installation, `init` selects Plaid Sandbox and prompts for the Plaid
client ID and secret with hidden input. Enter them only at these prompts; do not
put credentials in command arguments, environment variables, `.env` files, or
MCP client configuration. They are encrypted into the local SQLite store; the
encryption key is kept separately at
`~/.config/studio-saelix-finance/master.key`.
Plaid access tokens are encrypted in the local database as well. The
administrator lifecycle uses POSIX file permissions and locking, so the current
supported platforms are Linux and macOS.

The financial cache is intentionally plaintext inside the owner-protected
database. Phase 2 protects the Plaid secret and access tokens against theft of
the database alone; it does not provide full database encryption.

Configure Hermes with one secret-free stdio server:

```json
{
  "command": "uvx",
  "args": [
    "--from", "studio-saelix-finance==0.1.0",
    "studio-saelix-finance-mcp"
  ]
}
```

Pin the version used by Hermes deliberately. Upgrade or rollback by changing
the exact version in that configuration. The runtime is launched on demand;
no daemon, port, Docker container, or reverse proxy is required.

Persistent paths follow XDG conventions:

```text
~/.config/studio-saelix-finance/config.toml   # non-secret configuration
~/.config/studio-saelix-finance/master.key    # owner-only key
~/.local/share/studio-saelix-finance/finance.db
~/.local/state/studio-saelix-finance/finance.log
```

The administrator-managed non-secret configuration is stored at
`~/.config/studio-saelix-finance/config.toml`; new installations default to
Canada (`CA`) and Plaid Sandbox. Production is a deliberate administrator
action and must not be used before Sandbox commissioning and the separate
security/completion approval.

## Development

```bash
uv sync --extra dev
uv run pytest -q
uv run ruff check src tests
```

Tests use fake credentials and isolated temporary encrypted SQLite databases.
Plaid Sandbox tests are opt-in and require `.env.test`; production credentials
are not required.

Plaid Link and institution lifecycle helpers remain in the source tree for a future administrator-only interface, but they are not registered with FastMCP or exposed by the runtime executable.

This project retains the MIT license and inherited attribution in `LICENSE`.
