Phase 4: contacts & fittings — reads + guarded writes (#25, #26)

Contacts: read character/corp/alliance contacts; guarded add/remove of
character contacts. Fittings: read saved fits; guarded create/delete.
EsiClient.delete now takes params. All writes go through write-safety.

Closes #25, #26. 120 tests, coverage 89%.

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

src/familiar/contacts.py

@@ -0,0 +1,106 @@
+"""Contacts: read (character, corp, alliance) plus guarded character writes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+
+from . import auth, writes
+from .charutil import corporation_id, run_per_character, run_per_corp, summarize
+from .esi import client
+
+
+async def get_contacts(character: str | int | None = None, limit: int = 50) -> dict[str, Any]:
+    """Personal contacts for one character or all."""
+
+    async def fetch(token: str, cid: int) -> dict[str, Any]:
+        contacts = await client().get_all_pages(f"/characters/{cid}/contacts/", token=token)
+        return summarize(contacts, limit)
+
+    return await run_per_character(character, fetch)
+
+
+async def get_corp_contacts(character: str | int | None = None, limit: int = 50) -> dict[str, Any]:
+    """Corp contacts (needs a corp role) for one character's corp or all."""
+
+    async def fetch(token: str, corp_id: int, cid: int) -> dict[str, Any]:
+        contacts = await client().get_all_pages(f"/corporations/{corp_id}/contacts/", token=token)
+        return summarize(contacts, limit)
+
+    return await run_per_corp(character, fetch)
+
+
+async def get_alliance_contacts(
+    character: str | int | None = None, limit: int = 50
+) -> dict[str, Any]:
+    """Alliance contacts, resolved via each character's corp's alliance."""
+
+    async def fetch(token: str, cid: int) -> dict[str, Any]:
+        corp_id = await corporation_id(cid)
+        corp = await client().get(f"/corporations/{corp_id}/")
+        alliance_id = corp.get("alliance_id")
+        if not alliance_id:
+            return {"alliance_id": None, "count": 0, "sample": []}
+        contacts = await client().get_all_pages(f"/alliances/{alliance_id}/contacts/", token=token)
+        return {"alliance_id": alliance_id, **summarize(contacts, limit)}
+
+    return await run_per_character(character, fetch)
+
+
+async def add_contacts(
+    character: str | int,
+    contact_ids: list[int],
+    standing: float = 0.0,
+    confirm: bool = False,
+) -> dict[str, Any]:
+    """Add personal contacts with a standing. WRITE — guarded by write-safety."""
+    cid = auth.resolve_character(character)
+
+    async def execute() -> Any:
+        token, _ = await auth.get_auth(cid)
+        return await client().post(
+            f"/characters/{cid}/contacts/",
+            json=contact_ids,
+            params={"standing": standing},
+            token=token,
+        )
+
+    return await writes.guard(
+        "add_contacts",
+        {"character_id": cid, "contact_ids": contact_ids, "standing": standing},
+        confirm,
+        execute,
+    )
+
+
+async def remove_contacts(
+    character: str | int, contact_ids: list[int], confirm: bool = False
+) -> dict[str, Any]:
+    """Remove personal contacts. WRITE — guarded by write-safety."""
+    cid = auth.resolve_character(character)
+
+    async def execute() -> Any:
+        token, _ = await auth.get_auth(cid)
+        return await client().delete(
+            f"/characters/{cid}/contacts/", params={"contact_ids": contact_ids}, token=token
+        )
+
+    return await writes.guard(
+        "remove_contacts", {"character_id": cid, "contact_ids": contact_ids}, confirm, execute
+    )
+
+
+TOOLS = [
+    get_contacts,
+    get_corp_contacts,
+    get_alliance_contacts,
+    add_contacts,
+    remove_contacts,
+]
+
+
+def register(mcp: FastMCP) -> None:
+    """Register the contacts tools onto the given server."""
+    for fn in TOOLS:
+        mcp.tool(fn)

src/familiar/esi.py

@@ -72,8 +72,10 @@ class EsiClient:
     ) -> Any:
         return await self._request("PUT", path, params=params, json=json, token=token)
 
-    async def delete(self, path: str, token: str | None = None) -> Any:
-        return await self._request("DELETE", path, token=token)
+    async def delete(
+        self, path: str, params: dict[str, Any] | None = None, token: str | None = None
+    ) -> Any:
+        return await self._request("DELETE", path, params=params, token=token)
 
     async def get_all_pages(
         self, path: str, params: dict[str, Any] | None = None, token: str | None = None

src/familiar/fittings.py

@@ -0,0 +1,71 @@
+"""Ship fittings: read plus guarded create/delete writes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+
+from . import auth, writes
+from .charutil import run_per_character, summarize
+from .esi import client
+
+
+async def get_fittings(character: str | int | None = None, limit: int = 50) -> dict[str, Any]:
+    """Saved ship fittings for one character or all."""
+
+    async def fetch(token: str, cid: int) -> dict[str, Any]:
+        fits = await client().get(f"/characters/{cid}/fittings/", token=token) or []
+        return summarize(fits, limit)
+
+    return await run_per_character(character, fetch)
+
+
+async def create_fitting(
+    character: str | int, fitting: dict[str, Any], confirm: bool = False
+) -> dict[str, Any]:
+    """Save a new fitting. WRITE — guarded by write-safety.
+
+    ``fitting`` is an ESI fitting object: ``name``, ``description``,
+    ``ship_type_id``, and ``items`` (list of ``{type_id, flag, quantity}``).
+    """
+    cid = auth.resolve_character(character)
+
+    async def execute() -> Any:
+        token, _ = await auth.get_auth(cid)
+        return await client().post(f"/characters/{cid}/fittings/", json=fitting, token=token)
+
+    return await writes.guard(
+        "create_fitting",
+        {
+            "character_id": cid,
+            "name": fitting.get("name"),
+            "ship_type_id": fitting.get("ship_type_id"),
+        },
+        confirm,
+        execute,
+    )
+
+
+async def delete_fitting(
+    character: str | int, fitting_id: int, confirm: bool = False
+) -> dict[str, Any]:
+    """Delete a saved fitting. WRITE — guarded by write-safety."""
+    cid = auth.resolve_character(character)
+
+    async def execute() -> Any:
+        token, _ = await auth.get_auth(cid)
+        return await client().delete(f"/characters/{cid}/fittings/{fitting_id}/", token=token)
+
+    return await writes.guard(
+        "delete_fitting", {"character_id": cid, "fitting_id": fitting_id}, confirm, execute
+    )
+
+
+TOOLS = [get_fittings, create_fitting, delete_fitting]
+
+
+def register(mcp: FastMCP) -> None:
+    """Register the fittings tools onto the given server."""
+    for fn in TOOLS:
+        mcp.tool(fn)

src/familiar/server.py

@@ -15,8 +15,10 @@ from . import (
     __version__,
     account,
     comms,
+    contacts,
     corp,
     corp_economy,
+    fittings,
     industry,
     killmails,
     market,
@@ -87,3 +89,7 @@ misc.register(mcp)
 
 # Phase 4: mail & calendar (read + guarded writes).
 comms.register(mcp)
+
+# Phase 4: contacts & fittings (read + guarded writes).
+contacts.register(mcp)
+fittings.register(mcp)

tests/test_contacts_fittings.py

@@ -0,0 +1,97 @@
+"""Contacts and fittings: reads + guarded writes."""
+
+import asyncio
+
+import httpx
+import pytest
+
+from conftest import route
+from familiar import auth, contacts, fittings, writes
+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
+
+
+@pytest.fixture
+def writes_on(tmp_path, monkeypatch):
+    monkeypatch.setenv("FAMILIAR_DATA_DIR", str(tmp_path))
+    monkeypatch.setenv("FAMILIAR_ENABLE_WRITES", "true")
+
+
+def test_get_contacts(mock_esi, fake_auth):
+    mock_esi(lambda r: route(r, {"/contacts/": [{"contact_id": 1, "standing": 5.0}]}))
+    res = asyncio.run(contacts.get_contacts())
+    assert res["characters"][0]["count"] == 1
+
+
+def test_alliance_contacts(mock_esi, fake_auth):
+    fixtures = {
+        "/characters/99/": {"corporation_id": 2000},
+        "/corporations/2000/": {"alliance_id": 3000},
+        "/alliances/": [{"contact_id": 7}],
+    }
+    mock_esi(lambda r: route(r, fixtures))
+    res = asyncio.run(contacts.get_alliance_contacts())
+    assert res["characters"][0]["alliance_id"] == 3000
+    assert res["characters"][0]["count"] == 1
+
+
+def test_add_contacts_dry_run(mock_esi, fake_auth):
+    posted = []
+    mock_esi(lambda r: (posted.append(r), httpx.Response(200, json=[1]))[1])
+    res = asyncio.run(contacts.add_contacts(99, [1, 2], standing=5.0))
+    assert res["dry_run"] is True
+    assert not posted
+
+
+def test_remove_contacts_executes(mock_esi, fake_auth, writes_on):
+    mock_esi(lambda r: httpx.Response(204, content=b""))
+    res = asyncio.run(contacts.remove_contacts(99, [1], confirm=True))
+    assert res["executed"] is True
+
+
+def test_get_fittings(mock_esi, fake_auth):
+    mock_esi(lambda r: route(r, {"/fittings/": [{"fitting_id": 1, "name": "PvP Rifter"}]}))
+    res = asyncio.run(fittings.get_fittings())
+    assert res["characters"][0]["count"] == 1
+
+
+def test_create_fitting_disabled_raises(mock_esi, fake_auth, tmp_path, monkeypatch):
+    monkeypatch.setenv("FAMILIAR_DATA_DIR", str(tmp_path))
+    monkeypatch.delenv("FAMILIAR_ENABLE_WRITES", raising=False)
+    mock_esi(lambda r: httpx.Response(201, json={"fitting_id": 5}))
+    with pytest.raises(writes.WriteDisabled):
+        asyncio.run(fittings.create_fitting(99, {"name": "x"}, confirm=True))
+
+
+def test_create_fitting_executes(mock_esi, fake_auth, writes_on):
+    mock_esi(lambda r: httpx.Response(201, json={"fitting_id": 5}))
+    res = asyncio.run(fittings.create_fitting(99, {"name": "x", "ship_type_id": 587}, confirm=True))
+    assert res["executed"] is True
+    assert res["result"]["fitting_id"] == 5
+
+
+def test_contacts_fittings_registered():
+    tools = {t.name for t in asyncio.run(mcp.list_tools())}
+    assert {
+        "get_contacts",
+        "get_corp_contacts",
+        "get_alliance_contacts",
+        "add_contacts",
+        "remove_contacts",
+        "get_fittings",
+        "create_fitting",
+        "delete_fitting",
+    } <= tools