Instagram-Alpic-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repo. See README.md for full user-facing docs.

What this is

A single-user MCP server exposing Instagram actions via the Composio SDK, deployed on Alpic. Entry point: src/server.py (FastMCP, streamable-HTTP transport). Sibling project to D:\Personal\Linkedin-alpic-mcp — same architecture, same production fixes, different toolkit.

Commands

uv run python -m src.server   # run locally
uv run pytest                 # run tests
uv run ruff check .           # lint

Required environment

Both are mandatory — the server raises KeyError at startup if either is missing:

• COMPOSIO_API_KEY — must be a project-scoped Composio API key, not a playground key. Playground keys are hard-locked server-side to one bound user; any other user_id gets a 403 (user_id does not match the user this playground API key is locked to) that no client-side code can work around.
• COMPOSIO_USER_ID — the Composio account's actual user id.

Gotchas (all discovered the hard way on the LinkedIn sibling project, apply here too)

• .env / .env.example are write-protected by a local security hook (secret-file path guard). Edits to those files must be pasted in manually by the user, not written by the agent.
• Alpic's managed Python runtime does not use this repo's Dockerfile — it builds directly from pyproject.toml with its own buildpack (uv sync-style), running the process out of /var/task with a read-only $HOME. Don't assume a Dockerfile ENV change takes effect on Alpic; env vars need to be set via alpic environment-variable add (or the dashboard) too.
• Composio's SDK creates a cache dir at $HOME/.composio at import time — crashes immediately on any read-only-home sandbox unless COMPOSIO_CACHE_DIR points somewhere writable (/tmp works). This is a Composio/platform issue, not toolkit-specific.
• logger.py's file handler and stats.py's _save() are both wrapped in try/except OSError for the same reason — don't remove that, a read-only filesystem must degrade gracefully (stdout-only logging, in-memory-only stats), never crash the server.
• ENABLED_INSTAGRAM_TOOLS in composio_client.py is a curated list, not "every Instagram action Composio supports" — it reflects what's actually enabled for this account's auth config. Both session creation (_get_session) and discovery (list_instagram_tools) are scoped to it.
• ComposioClient._get_session() is lazily created and cached per instance — one Composio session per server process, not per request.
• execute() deliberately has no automatic retry (unlike check_connection/list_instagram_tools) because retrying an ambiguous write (e.g. creating a post, sending a DM) can duplicate it.
• The README's "Available Instagram Tools" parameter list is best-effort (inferred from action names, not live-fetched schemas) until the Composio connection for this account is completed — call instagram_mcp_list_tools once connected and update the README with the real schemas, the way the LinkedIn project's README was built from a live list_linkedin_tools() call.