Linkedin-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 LinkedIn actions via the Composio SDK, deployed on Alpic. Entry point: src/server.py (FastMCP, streamable-HTTP transport).

Commands

uv run python -m src.server   # run locally
uv run pytest                 # run tests (26 tests, mocked Composio SDK boundary)
uv run ruff check .           # lint

Required environment

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

• COMPOSIO_API_KEY — the Composio API key.
• COMPOSIO_USER_ID — the Composio account's user id. This must be the actual Composio user id, not the API key. An earlier version of composio_client.py assumed a playground-scoped key doubles as its own user id — that assumption was wrong and caused a 403 user_id does not match the user... at runtime. Don't reintroduce that shortcut.

COMPOSIO_PROJECT_ID, COMPOSIO_ORG_ID, COMPOSIO_ORG_MEMBER_EMAIL are optional and currently unused by any code path — the Composio(...) SDK constructor only accepts api_key/base_url/ environment/etc. (see .venv/Lib/site-packages/composio/sdk.py:SDKConfig). They're kept in .env for reference; don't invent SDK params to force them in.

Gotchas

• .env and .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.
• 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_linkedin_tools) because retrying an ambiguous write (e.g. creating a post) can duplicate it on LinkedIn.