Metadata-Version: 2.4
Name: alpflo-openwealth-mcp
Version: 0.1.1
Summary: OpenWealth MCP Server - AI agent integration with Swiss wealth management systems via bLink gateway
Project-URL: Homepage, https://github.com/alpflo/openwealth-mcp
Project-URL: Documentation, https://github.com/alpflo/openwealth-mcp/blob/main/README.md
Project-URL: Repository, https://github.com/alpflo/openwealth-mcp
Project-URL: Issues, https://github.com/alpflo/openwealth-mcp/issues
Author-email: Nariman Maddah <info@alpflo.dev>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agent,blink,mcp,model-context-protocol,openwealth,swiss-banking,wealth-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: structlog>=23.0
Provides-Extra: dev
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Description-Content-Type: text/markdown

# openwealth-mcp

OpenWealth MCP Server for Claude — enabling conversational AI agents to query Swiss wealth management data via OpenWealth APIs.

**Status:** Phase 3 - Publication Ready — V3 API complete, test PyPI validation in progress ✅

[![Tests](https://github.com/alpflo/openwealth-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/alpflo/openwealth-mcp/actions/workflows/test.yml)
[![Integration Tests](https://github.com/alpflo/openwealth-mcp/actions/workflows/integration-tests.yml/badge.svg)](https://github.com/alpflo/openwealth-mcp/actions/workflows/integration-tests.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)

---

## What Is This?

An open-source MCP (Model Context Protocol) server that enables AI agents to interact with Swiss wealth management systems through the **OpenWealth API v3.2.0 standard** (Custody Services API).

This server provides a standardized interface for AI assistants like Claude to:

- **List customers** in the portfolio (cursor-based pagination)
- **Get positions** for portfolio holdings and asset allocation
- **Get transactions** for trade history and cash movements

**Phase 1 Scope:** Read-only operations only (Custody Services API). Write operations excluded.

Built with Python 3.11+ and designed for Swiss financial institutions using the OpenWealth standard.

---

## Development Setup (Current)

### Prerequisites

- Python 3.11+
- `uv` package manager ([install here](https://github.com/astral-sh/uv))
- OpenWealth sandbox credentials (contact OpenWealth Association for access)

### Directory Structure

See [CLAUDE.md](CLAUDE.md#directory-structure) for complete structure and organization principles.

---

## Development Setup

See [CLAUDE.md](CLAUDE.md#development-commands) for complete setup instructions and development workflow.

**Quick start:**

```bash
# Install dependencies
uv sync

# Run tests
pytest tests/unit/ -v

# Type check
uv run pyright src/
```

**Authentication:** Add credentials to your shell profile (see [.env.example](.env.example)).

---

## Current MCP Tools

### Three Read-Only Tools (Specification Complete)

This project provides read-only access to portfolio and customer data via the **OpenWealth Custody Services API v3.2.0**.

| Tool | Purpose | Status |
|------|---------|--------|
| **`list_customers`** | Discover customers in OpenWealth | ✅ Spec ready |
| **`get_positions`** | Fetch portfolio holdings | ✅ Spec ready |
| **`get_transactions`** | Query transaction history | ✅ Spec ready |

**Scope:** Read-only Custody Services API operations only. Write operations and customer lifecycle management are excluded.

**Full API specifications:** See [`docs/API-REFERENCE.md`](./docs/API-REFERENCE.md)

---

## Architecture

```
Claude Desktop → MCP Server → OpenWealth Client → OpenWealth API (Sandbox)
```

**Key principles:** Type safety, stateless tools, structured logging, read-only operations.

See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for complete design philosophy and technical patterns.

---

## Documentation

| Document | Purpose |
|----------|---------|
| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Design principles + technical stack |
| [`docs/API-REFERENCE.md`](./docs/API-REFERENCE.md) | MCP tool schemas + examples |
| [`docs/TESTING.md`](./docs/TESTING.md) | Testing guide + coverage reports |
| [`docs/ROADMAP.md`](./docs/ROADMAP.md) | Development roadmap + milestones |

---

## Tech Stack

Python 3.11+ • Pydantic • MCP SDK • httpx • structlog

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for complete details.

---

## Installation

### From PyPI

```bash
pip install alpflo-openwealth-mcp
# or with uv
uv pip install alpflo-openwealth-mcp
```

### From Source (Development)

```bash
git clone https://github.com/alpflo/openwealth-mcp.git
cd openwealth-mcp
uv sync
uv run src/main.py
```

---

## Roadmap

- ✅ Phase 1: Foundation complete
- ✅ Phase 2: Implementation + testing complete (81.90% coverage)
- ✅ Phase 3: Published to PyPI v0.1.0

**Current Status:** Production release available on PyPI

---

## Contributing

Contributions are welcome! Please:

1. Read [CLAUDE.md](CLAUDE.md) for development setup and guidelines
2. Run tests locally: `pytest tests/unit/ -v`
3. Ensure type checking passes: `uv run pyright src/`
4. Follow Git workflow: feature branch → PR → review → merge

All contributions are licensed under Apache 2.0 (matching this repository).

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for design principles.

---

## License

**Apache License 2.0** — see [`LICENSE`](./LICENSE) for full text.

### Why Apache 2.0?

This project is licensed under Apache License 2.0 because:

1. **Explicit Patent Grant** — Protects users and contributors from patent litigation
2. **Business-Friendly** — Enables commercial use and proprietary extensions
3. **Permissive** — Allows free use, modification, and redistribution
4. **Industry Standard** — Widely adopted in AI tooling and wealth-tech ecosystems

### Third-Party Notices

This project includes third-party libraries under Apache 2.0, MIT, and BSD licenses.
See [`NOTICE`](./NOTICE) for complete attribution and license information.

All dependencies are compatible with Apache 2.0. No GPL-licensed code is included.

### Contributing

Contributions are welcome once the initial implementation is complete. All contributions
are implicitly licensed under Apache 2.0 (matching the repository license). We will not
require a separate Contributor License Agreement (CLA) but reserve the right to add one
if governance needs evolve.

For now, see [`CLAUDE.md`](./CLAUDE.md) for development guidelines.

---

## About

**Organization:** alpflo (GitHub: [@alpflo](https://github.com/alpflo))

**Purpose:** Enable AI agents to interact with Swiss wealth management systems through a standardized, type-safe interface.

**Status:** Production release v0.1.0 available on PyPI.

---

## Resources

- **OpenWealth Association:** <https://openwealth.swiss>
- **MCP Protocol:** <https://modelcontextprotocol.io>
- **Claude Desktop:** <https://claude.ai/download>

---

*Last updated: 2026-05-29*  
*Status: Phase 3 - Publication Ready ✅*
