liam-linkedin-ads-MCP: Instructions file for Codex

AGENTS.md

Guidance for AI agents and contributors working in this repo. Liam is an MCP server and CLI that creates ad campaigns on LinkedIn and Google Ads. Read this before changing code.

Architecture

pnpm + TypeScript monorepo:

• packages/shared — the platform-neutral layer: OAuth flow, credential stores, retry policy, the change journal and its lift windowing, named reporting periods, and the KPI math every platform shares. Anything here must be true of both platforms; anything true of only one belongs in that platform's package.
• packages/core — the LinkedIn engine. No UI. Owns the LinkedIn REST client, every resource module, audience hashing, targeting, conversions, and the Salesforce reader.
• packages/google — the Google Ads engine. Same shape as core: config and auth, one HTTP chokepoint, thin typed resource modules over GAQL, zod schemas reused as MCP inputs.
• packages/mcp — MCP server. src/tools.ts (LinkedIn) and src/googleTools.ts (gads_*) are shared by the stdio entry (src/index.ts) and the hosted Vercel route.
• packages/cli — the liam CLI (commander). LinkedIn at the top level, Google under liam google ... (src/google.ts).
• apps/web — Next.js app hosting the MCP over HTTP at /api/mcp (Vercel). Two tenants: the env-credential tenant gated by a MCP_AUTH_TOKEN bearer, and bring-your-own credentials callers who send X-Liads-* headers (client id/secret + refresh token, optional account id/version) that the route activates per request via withRequestCredentials (core/config.ts, AsyncLocalStorage).

Data flow: every tool/command builds a client via createLiads() (core/client.ts), which loads config + an auto-refreshing token provider, then calls a resource module. Resource modules are thin typed wrappers over LinkedInClient.request().

Conventions

• Nothing is ever created live. On LinkedIn, campaigns, campaign groups, and creatives default to DRAFT/intendedStatus: DRAFT. On Google, which has no draft status, campaigns, ad groups, and ads are created PAUSED and the schemas cannot express any other status. Never change either default. Activation is a separate, explicit, human step, and there is deliberately no tool for it on either platform.
• zod schemas are the source of truth. All tool/command inputs live as zod schemas in core/src/schemas.ts and are reused as MCP tool input schemas (Schema.shape). Add or change a field there first, then thread it through the resource module.
• Secrets never enter the repo. Local credentials live in ~/.liads/ (LinkedIn: config.json + credentials.json; Google: google.json + google-credentials.json, all mode 0600). Hosted credentials are LIADS_* / GADS_* env vars, or per-request X-Liads-* headers for bring-your-own-credentials callers. The config layer resolves request context first, then env, then files. Never log header credentials.
• The hosted MCP does not expose the Google tools, and must not start doing so. That endpoint is multi-tenant over per-request LinkedIn credentials while Google credentials would come from shared server env vars, so exposing them would let any caller operate the server's Google Ads account. registerTools(server, { google: false }) in the web route.
• Internal names are frozen. The package scope @liads/*, the ~/.liads dir, and the LIADS_* env prefix are intentionally NOT renamed to "liam" (renaming breaks stored creds and the deployed Vercel env). The brand "Liam" is visible-surface only. Google config shares ~/.liads for the same reason, and because the change journal at its root already spans both platforms.
• Match the surrounding code style. Keep comments at the existing density. No em dashes in user-facing strings.