Metadata-Version: 2.4
Name: alpflo-openwealth-mcp
Version: 0.1.0
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 (79.67% coverage)
- ✅ Phase 3: Publication (current - test PyPI validation)

See [docs/ROADMAP.md](docs/ROADMAP.md) for complete timeline.

---

## Contributing

Contributions will be welcome once the initial implementation is complete and the repository is made public.

For now, the project is in active development. Check back after the public launch.

---

## 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:** Pre-launch development. Repository will be made public once core implementation is complete.

---

## 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 ✅*
