finpy-mcp 0.1.0__tar.gz

finpy_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: finpy-mcp
+Version: 0.1.0
+Summary: Finpy MCP Server — AI-powered asset management through conversation
+Author: Robert Radoslav
+Author-email: Robert Radoslav <43938206+rbtrsv@users.noreply.github.com>
+Requires-Dist: click>=8.3.2
+Requires-Dist: fastmcp>=3.2.3
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+

finpy_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "finpy-mcp"
+version = "0.1.0"
+description = "Finpy MCP Server — AI-powered asset management through conversation"
+readme = "README.md"
+authors = [
+    { name = "Robert Radoslav", email = "43938206+rbtrsv@users.noreply.github.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.3.2",
+    "fastmcp>=3.2.3",
+    "httpx>=0.28.1",
+]
+
+[project.scripts]
+finpy-mcp = "finpy_mcp.server:main"
+finpy-cli = "finpy_mcp.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.15,<0.9.0"]
+build-backend = "uv_build"

finpy_mcp-0.1.0/src/finpy_mcp/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from finpy-mcp!")

finpy_mcp-0.1.0/src/finpy_mcp/cli.py

@@ -0,0 +1,191 @@
+"""
+Finpy CLI — Interactive terminal authentication
+
+Commands:
+  finpy-cli login       — Login via browser (OAuth device flow)
+  finpy-cli login --basic — Login with email/password in terminal (fallback)
+  finpy-cli logout      — Delete stored credentials
+  finpy-cli set-org     — Set active organization
+  finpy-cli status      — Show current auth status
+"""
+
+import getpass
+import time
+import webbrowser
+
+import click
+import httpx
+
+from .config import API_BASE_URL, REQUEST_TIMEOUT
+from .credentials import load_credentials, save_credentials, delete_credentials
+
+
+@click.group()
+def main():
+    """Finpy CLI — Authenticate and manage your Finpy MCP connection."""
+    pass
+
+
+def _save_and_show(data: dict) -> None:
+    """Save credentials and show orgs. Shared between login flows."""
+    token = data["token"]
+    user = data["data"]["user"]
+    orgs = data["data"]["organizations"]
+
+    # Default to first organization
+    default_org_id = orgs[0]["id"] if orgs else None
+
+    save_credentials({
+        "access_token": token["access_token"],
+        "refresh_token": token["refresh_token"],
+        "organization_id": default_org_id,
+        "user_email": user["email"],
+    })
+
+    click.echo(f"\n✓ Logged in as {user['email']}")
+    click.echo(f"✓ Credentials saved to ~/.finpy/credentials.json\n")
+
+    if orgs:
+        click.echo("Organizations:")
+        for org in orgs:
+            marker = " (active)" if org["id"] == default_org_id else ""
+            click.echo(f"  {org['id']}. {org['name']} — role: {org['user_role']}{marker}")
+        click.echo(f"\nUse 'finpy-cli set-org <id>' to change active organization.")
+    else:
+        click.echo("Warning: No organizations found. Create one in the Finpy dashboard.")
+
+
+@main.command()
+@click.option("--basic", is_flag=True, help="Use email/password login instead of browser (for headless environments)")
+def login(basic: bool):
+    """Login to Finpy. Opens browser by default (OAuth device flow).
+    Use --basic for email/password in terminal."""
+    if basic:
+        _login_basic()
+    else:
+        _login_device()
+
+
+def _login_device():
+    """Device flow: open browser, user approves, CLI polls for token."""
+    try:
+        with httpx.Client(timeout=REQUEST_TIMEOUT) as client:
+            # Step 1: Request device code
+            r = client.post(f"{API_BASE_URL}/accounts/auth/device-code")
+            r.raise_for_status()
+            device = r.json()
+
+            device_code = device["device_code"]
+            user_code = device["user_code"]
+            verification_url = device["verification_url"]
+            interval = device.get("interval", 2)
+            expires_in = device.get("expires_in", 300)
+
+            # Step 2: Open browser
+            click.echo(f"\nOpening browser to authorize...")
+            click.echo(f"If browser doesn't open, go to: {verification_url}")
+            click.echo(f"Code: {user_code}\n")
+            webbrowser.open(verification_url)
+
+            # Step 3: Poll for token
+            click.echo("Waiting for authorization", nl=False)
+            start = time.time()
+            while time.time() - start < expires_in:
+                time.sleep(interval)
+                click.echo(".", nl=False)
+
+                r = client.post(
+                    f"{API_BASE_URL}/accounts/auth/device-token",
+                    json={"device_code": device_code},
+                )
+                data = r.json()
+
+                if data.get("success"):
+                    click.echo("")  # newline after dots
+                    _save_and_show(data)
+                    return
+
+                error = data.get("error", "")
+                if error == "authorization_pending":
+                    continue
+                elif error == "expired_token":
+                    click.echo("\nError: Code expired. Please try again.", err=True)
+                    raise SystemExit(1)
+                elif error == "access_denied":
+                    click.echo("\nError: Authorization denied.", err=True)
+                    raise SystemExit(1)
+                else:
+                    click.echo(f"\nError: {error}", err=True)
+                    raise SystemExit(1)
+
+            click.echo("\nError: Timed out waiting for authorization.", err=True)
+            raise SystemExit(1)
+
+    except httpx.ConnectError:
+        click.echo(f"Error: Cannot connect to {API_BASE_URL}. Is the server running?", err=True)
+        raise SystemExit(1)
+
+
+def _login_basic():
+    """Basic flow: email/password in terminal (fallback for headless environments)."""
+    email = click.prompt("Email")
+    password = getpass.getpass("Password: ")
+
+    click.echo("Logging in...")
+
+    try:
+        with httpx.Client(timeout=REQUEST_TIMEOUT) as client:
+            r = client.post(
+                f"{API_BASE_URL}/accounts/auth/login",
+                json={"email": email, "password": password},
+            )
+
+            if r.status_code == 401:
+                click.echo("Error: Invalid email or password.", err=True)
+                raise SystemExit(1)
+
+            r.raise_for_status()
+            _save_and_show(r.json())
+
+    except httpx.HTTPStatusError as e:
+        click.echo(f"Error: API returned {e.response.status_code}", err=True)
+        raise SystemExit(1)
+    except httpx.ConnectError:
+        click.echo(f"Error: Cannot connect to {API_BASE_URL}. Is the server running?", err=True)
+        raise SystemExit(1)
+
+
+@main.command()
+def logout():
+    """Delete stored credentials."""
+    delete_credentials()
+    click.echo("✓ Logged out. Credentials deleted.")
+
+
+@main.command("set-org")
+@click.argument("org_id", type=int)
+def set_org(org_id: int):
+    """Set the active organization ID."""
+    creds = load_credentials()
+    if not creds:
+        click.echo("Error: Not logged in. Run 'finpy-cli login' first.", err=True)
+        raise SystemExit(1)
+
+    creds["organization_id"] = org_id
+    save_credentials(creds)
+    click.echo(f"✓ Active organization set to {org_id}")
+
+
+@main.command()
+def status():
+    """Show current authentication status."""
+    creds = load_credentials()
+    if not creds:
+        click.echo("Not authenticated. Run 'finpy-cli login' first.")
+        return
+
+    click.echo(f"Email: {creds.get('user_email', 'unknown')}")
+    click.echo(f"Organization ID: {creds.get('organization_id', 'not set')}")
+    click.echo(f"API: {API_BASE_URL}")
+    click.echo(f"Token: {'present' if creds.get('access_token') else 'missing'}")
+    click.echo(f"Refresh token: {'present' if creds.get('refresh_token') else 'missing'}")

finpy_mcp-0.1.0/src/finpy_mcp/client.py

@@ -0,0 +1,122 @@
+"""
+Finpy MCP Server — HTTP Client
+
+Async httpx wrapper that handles:
+- JWT authentication (from ~/.finpy/credentials.json)
+- Organization context (query param)
+- Entity context (for tools that need it)
+- Automatic token refresh on 401 responses
+"""
+
+import httpx
+
+from .config import API_BASE_URL, REQUEST_TIMEOUT
+from .credentials import load_credentials, save_credentials
+
+
+class FinpyClient:
+    """HTTP client for Finpy API with JWT auth and org/entity context."""
+
+    def __init__(self) -> None:
+        self.base_url = API_BASE_URL
+        self.organization_id: int | None = None
+        self.entity_id: int | None = None
+
+    def _get_credentials(self) -> dict:
+        """Load credentials or raise descriptive error."""
+        creds = load_credentials()
+        if not creds or not creds.get("access_token"):
+            raise RuntimeError(
+                "Not authenticated. Please run 'finpy-cli login' in your terminal first."
+            )
+        return creds
+
+    @property
+    def _headers(self) -> dict:
+        """Auth headers from stored credentials."""
+        creds = self._get_credentials()
+        return {"Authorization": f"Bearer {creds['access_token']}"}
+
+    @property
+    def _params(self) -> dict:
+        """Default query params (organization_id)."""
+        # Use org from credentials if not overridden
+        org_id = self.organization_id
+        if org_id is None:
+            creds = load_credentials()
+            if creds:
+                org_id = creds.get("organization_id")
+        params: dict = {}
+        if org_id is not None:
+            params["organization_id"] = org_id
+        return params
+
+    async def _refresh_token(self) -> bool:
+        """Attempt to refresh JWT using refresh_token. Returns True if successful."""
+        creds = load_credentials()
+        if not creds or not creds.get("refresh_token"):
+            return False
+
+        try:
+            async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as http:
+                r = await http.post(
+                    f"{self.base_url}/accounts/auth/refresh-token",
+                    json={"refresh_token": creds["refresh_token"]},
+                )
+                if r.status_code == 200:
+                    data = r.json()
+                    creds["access_token"] = data["token"]["access_token"]
+                    creds["refresh_token"] = data["token"]["refresh_token"]
+                    save_credentials(creds)
+                    return True
+        except httpx.HTTPError:
+            pass
+        return False
+
+    async def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Make HTTP request with auto-refresh on 401."""
+        params = {**self._params, **kwargs.pop("params", {})}
+
+        async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as http:
+            r = await http.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=self._headers,
+                params=params,
+                **kwargs,
+            )
+
+            # Auto-refresh on 401
+            if r.status_code == 401:
+                refreshed = await self._refresh_token()
+                if refreshed:
+                    r = await http.request(
+                        method,
+                        f"{self.base_url}{path}",
+                        headers=self._headers,
+                        params=params,
+                        **kwargs,
+                    )
+                else:
+                    raise RuntimeError(
+                        "Session expired. Please run 'finpy-cli login' again."
+                    )
+
+            r.raise_for_status()
+            return r.json()
+
+    async def get(self, path: str, **kwargs) -> dict:
+        """GET request to Finpy API."""
+        return await self._request("GET", path, **kwargs)
+
+    async def post(self, path: str, data: dict) -> dict:
+        """POST request to Finpy API."""
+        return await self._request("POST", path, json=data)
+
+    async def put(self, path: str, data: dict) -> dict:
+        """PUT request to Finpy API."""
+        return await self._request("PUT", path, json=data)
+
+
+# Singleton instance — shared across all tools
+finpy = FinpyClient()

finpy_mcp-0.1.0/src/finpy_mcp/config.py

@@ -0,0 +1,17 @@
+"""
+Finpy MCP Server — Configuration
+
+API base URL is read from FINPY_API_URL env var.
+Defaults to localhost for development, override for production.
+"""
+
+import os
+
+# API base URL — override with FINPY_API_URL env var for production
+API_BASE_URL = os.environ.get("FINPY_API_URL", "http://localhost:8001")
+
+# Credentials file path — where JWT + refresh token are stored locally
+CREDENTIALS_PATH = os.path.expanduser("~/.finpy/credentials.json")
+
+# HTTP client timeout (seconds)
+REQUEST_TIMEOUT = 30.0

finpy_mcp-0.1.0/src/finpy_mcp/credentials.py

@@ -0,0 +1,50 @@
+"""
+Finpy MCP Server — Credentials Management
+
+Reads/writes JWT + refresh token to ~/.finpy/credentials.json.
+File permissions set to 600 (owner read/write only).
+Password is NEVER stored — only tokens.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import TypedDict
+
+from .config import CREDENTIALS_PATH
+
+
+class Credentials(TypedDict):
+    access_token: str
+    refresh_token: str
+    organization_id: int | None
+    user_email: str
+
+
+def load_credentials() -> Credentials | None:
+    """Load credentials from ~/.finpy/credentials.json. Returns None if not found."""
+    path = Path(CREDENTIALS_PATH)
+    if not path.exists():
+        return None
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def save_credentials(creds: Credentials) -> None:
+    """Save credentials to ~/.finpy/credentials.json with chmod 600."""
+    path = Path(CREDENTIALS_PATH)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(creds, f, indent=2)
+    # Owner read/write only — no group/other access
+    os.chmod(path, 0o600)
+
+
+def delete_credentials() -> None:
+    """Delete credentials file (logout)."""
+    path = Path(CREDENTIALS_PATH)
+    if path.exists():
+        path.unlink()

finpy_mcp-0.1.0/src/finpy_mcp/server.py

@@ -0,0 +1,35 @@
+"""
+Finpy MCP Server
+
+FastMCP instance with all tools registered.
+Entrypoint: finpy-mcp (stdio transport for Claude Desktop/Code/Cursor)
+"""
+
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    "Finpy",
+    instructions=(
+        "Finpy Asset Manager — manage cap tables, deals, holdings, and financials through conversation.\n\n"
+        "IMPORTANT: Before using any tools, the user must have run 'finpy-cli login' in their terminal.\n"
+        "Then use set_context() to select an organization and entity.\n\n"
+        "Workflow: set_context → list/create data.\n"
+        "Entity is the foundation — everything (stakeholders, securities, deals, holdings) belongs to an entity.\n"
+        "Subscription is charged per entity — inform users when creating new entities."
+    ),
+    mask_error_details=True,
+)
+
+# Register all tools by importing tool modules
+# Each module uses @mcp.tool decorator from this instance
+from .tools import context  # noqa: F401, E402
+from .tools import entity  # noqa: F401, E402
+from .tools import captable  # noqa: F401, E402
+from .tools import deals  # noqa: F401, E402
+from .tools import holdings  # noqa: F401, E402
+from .tools import financials  # noqa: F401, E402
+
+
+def main():
+    """Entrypoint for finpy-mcp command. Runs stdio transport."""
+    mcp.run()