# Tranna MCP

Tranna MCP is a production-oriented [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server foundation for connecting Claude Desktop to future social-media and marketing platforms.

It provides a reusable connector framework, one disabled-by-default fake `ExampleConnector`, and optional Meta and Google connectors that call only official APIs. The Google connector supports GA4, Google Ads, Business Profile, Search Console, and YouTube Data/Analytics through one OAuth consent flow. The server always exposes the read-only diagnostic tool `tranna_get_service_status`.

## Start with Docker Compose

From this directory, run:

```bash
docker compose up
```

Docker Compose builds the image if needed and starts the server. The health endpoints are available at:

- `http://localhost:3000/healthz` — process liveness
- `http://localhost:3000/readyz` — MCP server readiness

Stop it with `Ctrl+C`, then run `docker compose down` if you also want to remove the container and network.

For configuration and Claude Desktop connection instructions, see [SETUP.md](SETUP.md).

## Architecture

```text
src/
├── authentication/  # Application authentication contracts; disabled placeholder only
├── configuration/   # Validated environment configuration
├── connectors/      # Reusable OAuth connector framework, registry, and fake example
├── server/          # MCP lifecycle, stdio transport, health server, state
├── tools/           # MCP tool registration and tool implementations
└── utilities/       # Structured logger and shared errors
```

The only transport enabled is the official MCP SDK's **stdio transport**, which is the normal local transport for Claude Desktop. Operational logs are written to stderr, leaving stdout exclusively for MCP JSON-RPC messages.

## Configuration

Copy `.env.example` to `.env` to adjust local Docker Compose settings. All values are validated at startup.

| Variable | Default | Purpose |
| --- | --- | --- |
| `NODE_ENV` | `production` in Docker | `development`, `test`, or `production` |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |
| `SERVICE_VERSION` | `0.1.0` | Version returned in server status |
| `HEALTH_ENABLED` | `true` | Enables the health HTTP server |
| `HEALTH_HOST` | `0.0.0.0` | Interface for health checks |
| `HEALTH_PORT` | `3000` | Health HTTP port for native execution |
| `HOST_HEALTH_PORT` | `3000` | Host port mapped by Docker Compose |
| `EXAMPLE_CONNECTOR_ENABLED` | `false` | Enables the fake demonstration connector and its fake-data MCP tool |
| `META_CONNECTOR_ENABLED` | `false` | Enables the real Meta connector after all required `META_*` values are supplied |
| `GOOGLE_CONNECTOR_ENABLED` | `false` | Enables the real Google connector after all required `GOOGLE_*` OAuth settings are supplied |

`docker-compose.yml` intentionally fixes the container health port to `3000`, because Docker's health check runs inside the container. Use `HOST_HEALTH_PORT` to change the host-facing port. Do not set `HEALTH_ENABLED=false` for the Compose service, because its health check requires the endpoint.

## Development and verification

Requires Node.js 24 or later.

```bash
npm install
npm run typecheck
npm test
npm run build
npm start
```

Use `npm run dev` for file-watching development. It loads `.env` when present.

## Meta connector

The Meta connector is disabled by default. When explicitly configured, it supports official Graph API access to Facebook Pages, linked Instagram professional accounts, and Marketing API campaign operations. OAuth credentials, Page access tokens, OAuth state, and discovered asset IDs are encrypted at rest with AES-256-GCM; tokens are never written to application logs or MCP tool output.

Read the detailed [Meta setup guide](docs/META_SETUP.md) before enabling it. The guide covers app creation, products, OAuth redirect settings, permissions, review/business-verification limits, all environment variables, the connection flow, and supported limitations.

`META_ALLOW_WRITE_OPERATIONS` defaults to `false`. Publishing, campaign creation, campaign state changes, and budget updates fail locally until it is explicitly set to `true`.

## Google connector

The Google connector is disabled by default. It uses Google's OAuth authorization-code flow and encrypts OAuth tokens and CSRF state at rest with AES-256-GCM. One `google_begin_connect` / `google_complete_connect` authorization requests the configured GA4, Google Ads, Business Profile, Search Console, and YouTube scopes. Tokens and authorization codes are never logged or returned by MCP tools.

Set `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_TOKEN_ENCRYPTION_KEY`, `GOOGLE_ADS_DEVELOPER_TOKEN`, and a currently supported `GOOGLE_ADS_API_VERSION`, then register the exact callback URI `http://localhost:3000/oauth/google/callback`. Enable the listed APIs in the Google Cloud project. `GOOGLE_ADS_LOGIN_CUSTOMER_ID` is optional and supports manager-account access. The connector sends transient 429/5xx failures through a bounded exponential retry policy.

`GOOGLE_ALLOW_WRITE_OPERATIONS` defaults to `false`. Review replies and YouTube uploads are locally rejected until it is explicitly enabled. `update_video_metadata` and `delete_video` are registered only when `GOOGLE_OAUTH_SCOPES` explicitly includes `https://www.googleapis.com/auth/youtube.force-ssl`. `publish_short` uploads content marked with `#Shorts`; YouTube makes the final Shorts eligibility determination.

The Google connector exposes direct provider operations only: OAuth lifecycle, GA4 accounts/properties/reports, Google Ads accounts/campaigns/metrics, Business Profile locations/reviews, Search Console sites/query/page rows, and supported YouTube data, analytics, and upload operations. Google Ads campaign tools are named `list_google_ads_campaigns` and `get_google_ads_campaign` to avoid collisions with Meta campaign tools. It intentionally has no recommendation, anomaly-detection, marketing-dashboard, or other marketing-intelligence layer.

Required Google Cloud APIs are Google Analytics Admin API, Google Analytics Data API, Google Ads API, Business Profile Account Management API, Business Profile Business Information API, Google My Business API (reviews), Search Console API, YouTube Data API v3, and YouTube Analytics API. The default scopes are `openid`, `email`, `profile`, Analytics read-only, Ads, Business Profile, Search Console read-only, and YouTube read-only/upload; `.env.example` contains each official scope URL. Add `https://www.googleapis.com/auth/youtube.force-ssl` only when video metadata update and deletion are needed.

## Current scope and platform limitations

The `ExampleConnector` remains a framework demonstration only: its OAuth client, token values, health check, capability, and MCP tool all use fixed local fake data and make no network calls. Meta and Google are the real platform connectors.

When adding a connector, use only the platform's documented official API and SDK, implement only approved scopes/capabilities, and document any access tier, app review, business verification, sandbox restriction, or unavailable capability. This project intentionally provides no unofficial API clients or web-scraping fallback.

## Connector framework

Every connector extends `AbstractConnector` and receives its dependencies through the constructor. The base class provides a uniform interface and implements configuration gating, lifecycle state, OAuth token persistence/refresh, health tracking, safe status snapshots, structured logging, and error conversion. It does not make provider calls itself.

| Method | Purpose |
| --- | --- |
| `connect()` | Runs the injected OAuth authorization flow and stores its returned token. |
| `disconnect()` | Optionally revokes the token through the injected OAuth client and clears local storage. |
| `refreshToken()` | Loads and refreshes a stored OAuth token without exposing it to MCP. |
| `health()` | Runs the connector-specific health check and returns a normalized result. |
| `status()` | Returns a token-free connection and configuration snapshot. |
| `capabilities()` | Lists provider features and documented limitations. |
| `registerTools()` | Registers connector MCP tools through a testable, narrow tool-registry boundary. |

`src/connectors/connector-registration.ts` is the automatic registration composition point. It creates each known connector using the application configuration and dependency injection. Disabled connectors remain visible in service status but do not register MCP tools and reject connection attempts.

### Creating a future connector

1. Confirm the exact official API capability, required OAuth scopes, approval requirements, and business-verification requirements.
2. Create a connector class under `src/connectors/<connector-name>/` that extends `AbstractConnector`.
3. Inject an official OAuth client, a secure production token store, logger, and connector configuration. Do not construct these inside the connector class.
4. Implement `oauthScopes`, `performHealthCheck`, and `registerConnectorTools`. Keep tool methods narrow and describe all limitations.
5. Add an enablement variable to `AppConfig` and `loadConfiguration`, then register the factory in `connector-registration.ts`.
6. Test the class directly with fake `OAuthClient`, `TokenStore`, logger, clock, and tool registrar dependencies. Do not test against a real provider in unit tests.

The included `ExampleConnector` follows this pattern and is covered by independent tests. It must not be copied as a real credential or token-storage implementation: `InMemoryTokenStore` and `ExampleOAuthClient` are demonstration-only.

## Production characteristics

- Exact MCP SDK version is pinned (`@modelcontextprotocol/sdk` `1.30.0`) for repeatable installs.
- Startup configuration is validated before serving requests.
- Structured JSON logging goes to stderr.
- Signal handling closes MCP and health resources cleanly.
- Docker runs as an unprivileged user with a read-only filesystem and a Docker health check.
- The image uses a multi-stage production build with development dependencies omitted.

## Extending safely

1. Follow the connector-framework process above.
2. Add only the supported OAuth authentication flow; never log tokens or authorization headers.
3. Register the connector factory in `src/connectors/connector-registration.ts`.
4. Add narrow MCP tools through `registerConnectorTools`, with clear descriptions and appropriate annotations.
5. Add configuration validation, tests, and documentation for the capability and any provider approval requirement.