Tattoo Pal

A calm, bounded way to spend time with the tattoo artists you admire — inside your AI chat, without Instagram's feed.

Tattoo Pal brings an artist's recent work to you one piece at a time, in a conversation, so you can sit with it, react, keep what resonates, and over time see how your own taste shows up across real work. It is the opposite of an infinite algorithmic scroll: you look at what you asked for and leave when you're done, not when a feed decides to release you.

Under the hood it is a Model Context Protocol (MCP) server. You point it at the artists you follow (by Instagram handle); from your chat client you can pull a merged feed, discover one post at a time, bookmark favourites, and record notes about your taste that a future session can reload. Recent work is fetched through Instagram's Business Discovery API.

The image renders inline only in ChatGPT. next_inspiration returns a ChatGPT Apps SDK widget that draws the preview image directly in the conversation. This matters because no other tested client shows the image inline — ChatGPT does not render raw MCP image blocks, and Claude receives the image but does not display it. Since actually seeing the work is the whole point, the product targets the ChatGPT connector over HTTP. A stdio transport exists for local development, but it does not render the image.

Read-and-curate only: Tattoo Pal never posts, comments, or messages, and previews are downscaled copies — see Attribution.

---

How it works

You ──▶ ChatGPT ──(OAuth-gated HTTP)──▶ Tattoo Pal (MCP server) ──▶ Instagram
                                            │                        Business
                          renders the  ◀────┘  next_inspiration        Discovery
                          Apps SDK widget       returns a widget +
                          (image inline)        downscaled preview

• MCP tools expose the actions (track artists, pull a feed, discover one piece, save, record taste). See The MCP tools.
• Two-layer codebase: all logic lives in a transport-agnostic core; a thin server adapter exposes it as MCP. See Repository layout.
• OAuth 2.1 resource server: in HTTP mode every request must carry a valid bearer token from your identity provider. An unauthenticated request gets 401 with a WWW-Authenticate: Bearer resource_metadata=... header (RFC 9728); the ChatGPT connector follows this to complete login automatically.
• The widget: the ≤640px preview travels as a data URL in the tool result's _meta, which the ChatGPT host forwards to the widget iframe without ever putting the base64 through the model's context window.

---

Repository layout

Code — src/tattoo_feed/

A deliberate two-layer split so a future GUI can reuse the logic without a rewrite. core knows nothing about MCP; server holds no business logic.

src/tattoo_feed/
  config.py            # lazy env config (IG_ACCESS_TOKEN, IG_USER_ID)
  errors.py            # typed error hierarchy (TattooFeedError + subclasses)
  models.py            # Pydantic v2 frozen value objects
  imaging.py           # preview downscale + EXIF strip (≤640px JPEG)
  repositories/        # Repository ABC + JSON-file stores (atomic writes)
  graph/client.py      # Instagram Business Discovery client
  services/            # Feed / Artist / Inspiration / Preference services
  server/app.py        # build_server() factory; MCP tools; stdio/HTTP entrypoint
  server/auth.py       # OAuth 2.1 JWT verifier (resource-server side)
  server/widgets/      # Apps SDK widget HTML, served as a ui:// MCP resource

tests/ mirrors this with a fully hermetic suite — Instagram HTTP is mocked with respx, JWKS with test-generated RSA keypairs, zero live network calls.

Non-code documentation

The repo keeps two kinds of written record alongside the code. Neither is needed to run the project; both are kept deliberately, as a window into how it was built.

• scratchpads/ — in-build engineering notes and design deep-dives. The working reasoning behind specific decisions and bug investigations, written as they happened: e.g. removing-the-global.md (why the module-level server global was removed), auth-wiring-seam.md and host-header-421.md (an auth refactor and the DNS-rebinding 421 it surfaced), rate-limiting.md, built-for-chatgpt.md. Think of these as the project's lab notebook.

• build_artifacts/ — an archived record of the phased build. The project was built in stages (Phase 1–Phase 3), each driven by its own governing docs — an implementation plan, a technical-contract reference, process rules, and an acceptance checklist — plus the autonomous build-loop scripts and the per-phase build logs. It is purely historical: a snapshot of how each stage was specified and run, not live configuration.

• Root docs — RETROACTIVE_PRD.md reconstructs, at product altitude, the why / for whom / what "good" means (a teaching artifact written after the fact); CLAUDE.md is the process governance for the build tooling.

---

Setup

Requirements: Python 3.12 and uv.

uv sync                 # create the venv and install pinned deps
cp .env.example .env    # then edit .env with your real credentials

Environment variables

Always required — Instagram credentials:

Variable	Meaning
IG_ACCESS_TOKEN	A long-lived Instagram Graph API access token.
IG_USER_ID	The Instagram Business/Creator account id that owns the token (not your Facebook user id).
TATTOO_FEED_DATA_DIR	Optional. Where the JSON stores live (default ./data).

Required for HTTP / ChatGPT mode — OAuth resource-server config:

Variable	Meaning
MCP_AUTH_ISSUER	Issuer URL of your IdP — must exactly match the token's iss claim.
MCP_AUTH_JWKS_URL	JWKS endpoint used to verify JWT signatures.
MCP_AUTH_AUDIENCE	Canonical public URL of this server — the RFC 8707 audience binding.
MCP_AUTH_REQUIRED_SCOPES	Comma-separated required scopes (blank for none).
NGROK_AUTHTOKEN / NGROK_DOMAIN	ngrok auth token and your reserved domain for stable TLS ingress.

.env is gitignored and must never be committed — only .env.example (with placeholders) is in the repo.

Getting Instagram credentials is a one-time manual step on Meta's side: create a Meta app, link an Instagram Business/Creator account to a Facebook Page, and mint a long-lived token with Business Discovery permission. The IG_USER_ID must be the Instagram account id (via GET /me/accounts?fields=instagram_business_account), not your Facebook user id.

---

Running

ChatGPT over HTTP — the product

./run-server.sh builds the image and starts the server + ngrok tunnel together (a thin wrapper over docker compose up --build):

cp .env.example .env            # fill in all values, including MCP_AUTH_* and NGROK_*
./run-server.sh

Then:

1. Open the ngrok inspector at http://localhost:4040 to confirm the public URL.
2. In ChatGPT, add a custom connector:
   • URL: https://<your-ngrok-domain>/mcp
   • Authentication: OAuth
3. ChatGPT walks through OAuth discovery and a browser login against your IdP, then lists the tools.

Identity provider. The server is IdP-agnostic — it only needs an issuer supporting OAuth 2.1 + PKCE, metadata discovery (RFC 8414 / OIDC), and the RFC 8707 resource indicator. Auth0 has a documented walkthrough for exactly this setup (Stytch, WorkOS, Descope are alternatives). Configure your IdP to issue tokens whose audience is the server's public URL (MCP_AUTH_AUDIENCE), and register a matching API/resource for it.

Stable domain. Reserve a domain at https://dashboard.ngrok.com/domains and set NGROK_DOMAIN in .env, so the public URL — and the connector configuration — survive restarts.

Local development (stdio)

A credential-free local entrypoint, useful for exercising the tools without a tunnel or IdP, and the transport the test suite boots over. It does not render the inspiration image — use ChatGPT for the visual experience.

uv run python -m tattoo_feed.server.app

Wire it into a local MCP client with command: "uv", args: ["run", "python", "-m", "tattoo_feed.server.app"], the project as cwd, and IG_ACCESS_TOKEN / IG_USER_ID in env.

---

The MCP tools

Tool	What it does
list_artists	List tracked artists.
add_artist(handle)	Validate the handle is a reachable professional account, then track it.
remove_artist(handle)	Stop tracking a handle.
get_feed(limit_per_artist=10)	Merged, newest-first feed — metadata + permalinks only (no images).
next_inspiration()	One not-yet-seen post, marked seen. Returns the Apps SDK widget; image renders inline only in ChatGPT.
save_to_inspiration(post_id, notes=None)	Bookmark a post into the saved collection.
list_inspiration()	The saved collection, in save order.
remove_from_inspiration(post_id)	Remove a saved item.
reset_seen()	Clear the seen-set so inspiration starts fresh.
record_preference(observation)	Persist a taste note (propose-then-confirm).
get_preference_summary()	All recorded preferences, to reload taste in a fresh session.

---

Design notes

• Two-layer split (core / server). MCP concepts never leak into core; business logic never leaks into server. A future GUI is a bolt-on, not a rewrite.
• JSON-file persistence behind a Repository interface. Simple, inspectable, swappable. Writes are atomic (temp file + os.replace) so a crash mid-write can't corrupt a store.
• Lazy credentials. The server boots and lists its tools with no network and no real credentials; tokens are read only when a tool calls Instagram or the auth middleware validates a bearer token.
• Constructor-injected auth via a factory. build_server(auth_cfg) is the single place a server instance is created, with auth supplied through the SDK's public auth= / token_verifier= parameters — no private-attribute writes. Passing None builds the unauthenticated stdio server.
• Widget image as a data URL in _meta. Only next_inspiration returns a rendered image — the one-at-a-time moment that earns the context. get_feed stays metadata-only to keep the context window light.
• Typed errors, frozen models, strict typing. Every external failure maps to a TattooFeedError; boundary data is validated once into immutable Pydantic v2 values; mypy --strict, ruff, and a 90% coverage floor are enforced.

---

Limitations (by design)

• Inline image rendering is ChatGPT-only — the Apps SDK widget is the one channel that shows the image; no other tested client displays it.
• No video, carousels show the first image only. Still imagery, filtered at the Graph-client layer.
• Single account. Wired to one Instagram account (IG_USER_ID); OAuth gates who may call, not which account is queried.
• Manual token refresh. No auto-refresh; an expired token fails with a clear TokenExpiredError.
• Resource-server only. The server validates tokens but does not issue them — it relies on an external IdP that must be configured first.
• Widget render is human-verified. The gate confirms the widget is registered and the _meta is present; whether the image actually paints in ChatGPT is an eyeball check.

---

Attribution & copyright

Posts belong to the artists who made them. This tool is for personal discovery and curation, not redistribution:

• Previews are downscaled copies (≤640px, EXIF stripped), never full-res.
• Every image and saved item carries the artist's handle and the post's permalink, so attribution travels with the content.
• Respect each artist's rights: don't repost or reuse their work without permission.

---

Development

The full gate (all must exit 0):

uv run ruff format --check .
uv run ruff check .
uv run mypy --strict src
uv run pytest -q --cov=src/tattoo_feed --cov-report=term-missing --cov-fail-under=90

License

MIT — see LICENSE.