Metadata-Version: 2.4
Name: alpflo-openwealth-mcp
Version: 0.1.2
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.

---

## Installation

### For End Users (Using the MCP Server)

**Prerequisites:**

- Python 3.11+ (check with `python --version`)
- Claude Desktop app ([download here](https://claude.ai/download))
- OpenWealth sandbox credentials (contact [OpenWealth Association](https://openwealth.swiss) for access)

**Step 1: Install the package**

```bash
pip install alpflo-openwealth-mcp
```

**Step 2: Configure Claude Desktop**

Add this to your Claude Desktop configuration file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "openwealth": {
      "command": "python",
      "args": ["-m", "openwealth_mcp"],
      "env": {
        "OPEN_WEALTH_USER": "your_username_here",
        "OPEN_WEALTH_PASSWORD": "your_password_here",
        "OPEN_WEALTH_BASE_URL": "https://api.openwealth.synpulse8.com/api/custody-services/v3"
      }
    }
  }
}
```

**Step 3: Restart Claude Desktop**

The OpenWealth tools will now be available in your Claude conversations:

- `list_customers` — Discover customers in your portfolio
- `get_positions` — View portfolio holdings and asset allocation
- `get_transactions` — Query transaction history

**Example usage in Claude:**

```
Show me all customers in my portfolio
What positions does customer C001 hold?
Get transactions for customer C001 in the last 30 days
```

### Troubleshooting

**"Server disconnected" error:**

If Claude Desktop shows "Server disconnected", the package may not be installed globally:

```bash
# Install globally with pip
pip3 install alpflo-openwealth-mcp

# Or use the full path to your Python in the config
# macOS example:
{
  "mcpServers": {
    "openwealth": {
      "command": "/Library/Frameworks/Python.framework/Versions/3.13/bin/python3",
      "args": ["-m", "openwealth_mcp"],
      "env": { ... }
    }
  }
}
```

**Check installation:**
```bash
python3 -c "import openwealth_mcp; print(openwealth_mcp.__version__)"
```

---

## Development Setup

**For Contributors** (developing the MCP server itself)

### Prerequisites

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

### Quick Start

```bash
# Clone repository
git clone https://github.com/alpflo/openwealth-mcp.git
cd openwealth-mcp

# Install dependencies
uv sync

# Run tests
pytest tests/unit/ -v

# Type check
uv run pyright src/
```

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

---

## 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.

---

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