Phase 4: corp economy & facilities reads (#33, #20)

Add read-only corp tools: wallets, assets, mining observers, facilities,
starbases — all corp-level (need corp roles). Closes #33 and completes the
remaining corp items of #20.

100 tests, coverage 91%.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/familiar/corp_economy.py

@@ -0,0 +1,84 @@
+"""Read-only corp economy & facilities tools.
+
+Corp wallets, assets, mining, facilities, and starbases — all corp-level, so
+they need the relevant corp role (ESI returns 403 otherwise). Keyed off each
+logged-in character's corporation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+
+from .charutil import run_per_corp, summarize
+from .esi import client
+
+
+async def get_corp_wallets(character: str | int | None = None) -> dict[str, Any]:
+    """Balances of the corp's wallet divisions (needs Accountant/Junior Accountant)."""
+
+    async def fetch(token: str, corp_id: int, cid: int) -> dict[str, Any]:
+        wallets = await client().get(f"/corporations/{corp_id}/wallets/", token=token) or []
+        return {"wallets": wallets}
+
+    return await run_per_corp(character, fetch)
+
+
+async def get_corp_assets(character: str | int | None = None, limit: int = 20) -> dict[str, Any]:
+    """Corp assets (needs Director) for one character's corp or all."""
+
+    async def fetch(token: str, corp_id: int, cid: int) -> dict[str, Any]:
+        assets = await client().get_all_pages(f"/corporations/{corp_id}/assets/", token=token)
+        return summarize(assets, limit)
+
+    return await run_per_corp(character, fetch)
+
+
+async def get_corp_mining(character: str | int | None = None, limit: int = 20) -> dict[str, Any]:
+    """Corp mining observers (moon drills etc.) — needs the Accountant role."""
+
+    async def fetch(token: str, corp_id: int, cid: int) -> dict[str, Any]:
+        observers = await client().get_all_pages(
+            f"/corporation/{corp_id}/mining/observers/", token=token
+        )
+        return summarize(observers, limit)
+
+    return await run_per_corp(character, fetch)
+
+
+async def get_corp_facilities(
+    character: str | int | None = None, limit: int = 20
+) -> dict[str, Any]:
+    """Corp industry facilities (needs the Factory Manager role)."""
+
+    async def fetch(token: str, corp_id: int, cid: int) -> dict[str, Any]:
+        facilities = await client().get(f"/corporations/{corp_id}/facilities/", token=token) or []
+        return summarize(facilities, limit)
+
+    return await run_per_corp(character, fetch)
+
+
+async def get_corp_starbases(character: str | int | None = None, limit: int = 20) -> dict[str, Any]:
+    """Corp starbases / POSes (needs the Director role)."""
+
+    async def fetch(token: str, corp_id: int, cid: int) -> dict[str, Any]:
+        starbases = await client().get_all_pages(f"/corporations/{corp_id}/starbases/", token=token)
+        return summarize(starbases, limit)
+
+    return await run_per_corp(character, fetch)
+
+
+TOOLS = [
+    get_corp_wallets,
+    get_corp_assets,
+    get_corp_mining,
+    get_corp_facilities,
+    get_corp_starbases,
+]
+
+
+def register(mcp: FastMCP) -> None:
+    """Register the corp economy tools onto the given server."""
+    for fn in TOOLS:
+        mcp.tool(fn)

src/familiar/server.py

@@ -15,6 +15,7 @@ from . import (
     __version__,
     account,
     corp,
+    corp_economy,
     industry,
     killmails,
     market,
@@ -75,3 +76,6 @@ profile.register(mcp)
 
 # Phase 4: corp organization (read-only, needs corp roles).
 corp.register(mcp)
+
+# Phase 4: corp economy & facilities (read-only, needs corp roles).
+corp_economy.register(mcp)

tests/test_corp_economy.py

@@ -0,0 +1,76 @@
+"""Corp economy & facilities tools (auth & ESI mocked)."""
+
+import asyncio
+
+import pytest
+
+from conftest import route
+from familiar import auth, corp_economy
+from familiar.server import mcp
+
+CHARS = [{"character_id": 99, "character_name": "Alpha", "scopes": []}]
+
+
+@pytest.fixture
+def fake_auth(monkeypatch):
+    monkeypatch.setattr(auth, "list_characters", lambda: list(CHARS))
+
+    async def get_auth(cid, **kw):
+        return f"token-{cid}", cid
+
+    monkeypatch.setattr(auth, "get_auth", get_auth)
+    monkeypatch.setattr(auth, "resolve_character", lambda i: 99)
+    return CHARS
+
+
+def test_corp_wallets(mock_esi, fake_auth):
+    fixtures = {
+        "/wallets/": [{"division": 1, "balance": 1000.0}],
+        "/characters/": {"corporation_id": 2000},
+    }
+    mock_esi(lambda r: route(r, fixtures))
+    res = asyncio.run(corp_economy.get_corp_wallets())
+    entry = res["characters"][0]
+    assert entry["corporation_id"] == 2000
+    assert entry["wallets"][0]["balance"] == 1000.0
+
+
+def test_corp_assets_paginated(mock_esi, fake_auth):
+    fixtures = {
+        "/assets/": [{"item_id": 1}, {"item_id": 2}],
+        "/characters/": {"corporation_id": 2000},
+    }
+    mock_esi(lambda r: route(r, fixtures))
+    res = asyncio.run(corp_economy.get_corp_assets())
+    assert res["characters"][0]["count"] == 2
+
+
+def test_corp_mining(mock_esi, fake_auth):
+    fixtures = {
+        "/mining/observers/": [{"observer_id": 5}],
+        "/characters/": {"corporation_id": 2000},
+    }
+    mock_esi(lambda r: route(r, fixtures))
+    res = asyncio.run(corp_economy.get_corp_mining())
+    assert res["characters"][0]["count"] == 1
+
+
+def test_corp_facilities_and_starbases(mock_esi, fake_auth):
+    fixtures = {
+        "/facilities/": [{"facility_id": 1}],
+        "/characters/": {"corporation_id": 2000},
+    }
+    mock_esi(lambda r: route(r, fixtures))
+    res = asyncio.run(corp_economy.get_corp_facilities())
+    assert res["characters"][0]["count"] == 1
+
+
+def test_corp_economy_tools_registered():
+    tools = {t.name for t in asyncio.run(mcp.list_tools())}
+    assert {
+        "get_corp_wallets",
+        "get_corp_assets",
+        "get_corp_mining",
+        "get_corp_facilities",
+        "get_corp_starbases",
+    } <= tools