# EE Content Atlas

Canonical page: https://agents.everythingsenergy.show
MCP endpoint: https://agents.everythingsenergy.show/mcp
REST endpoint: https://agents.everythingsenergy.show/search
Download endpoint: https://agents.everythingsenergy.show/download
Service version: 0.7.0
Audience: approved Everything's Energy collaborators and authorized AI agents.

## Purpose

EE Content Atlas is a shared anthology and creative workbench for people and AI agents. It helps collaborators discover episode moments, inspect transcript and asset context, choose usable English or Spanish clip variants, download selected files, and amplify source-backed material into platform-specific creative work.

Core flow: Discover -> Understand -> Amplify.

## Access

Requests require an access key issued by the Everything's Energy team:

Authorization: Bearer <CATALOG_READER_TOKEN>

Store the key only in a product secret field, user-level MCP configuration, or local untracked env file with private permissions. Never commit it, print it, paste it into chat, or place it in project docs.

## Agent First Contact

1. Initialize the MCP endpoint.
2. Call `tools/list` to inspect the live role-scoped registry.
3. Call `ee_clip_suggested_workflows` with the user's latest intent when it is already known. Do not ask the user to repeat it merely to populate the tool.
4. Call `ee_clip_catalog_status` when freshness, language coverage, transcript coverage, or supported controls matter.
5. Call `ee_clip_search` with `search_scope=both` and an explicit destination platform when known.
6. Prefer a suitable existing clip; inspect dimensions, language, orientation, caption treatment, transcript evidence, and grouped variants.
7. Call `ee_clip_asset_download` after selecting an exact existing asset ID.
8. If no existing clip satisfies the brief, call `ee_clip_narrative_plan`, then create a production spec and job.
9. Inspect the portrait contact sheet and approve or revise it before render.
10. Use the selected or newly created clip and transcript-backed context to prepare platform-specific post content when that advances the user's request.
11. Continue through the next safe action instead of stopping at tool discovery when the requested deliverable can be completed.

## Agent-Guided Interface

The latest explicit user request in the calling conversation controls. Workflows route and enrich that request; they do not replace, narrow, or delay it without a loadbearing reason.

Every MCP tool result preserves its original top-level fields and sandwiches them between:

- `agent_guidance_before`: the intent inferred from tool arguments, intent precedence, and the operating instruction for reading the payload;
- the unchanged result fields;
- `agent_guidance_after`: direct next actions, a concise user-facing delivery pattern, and proactive completion guidance.

Workflow and deliverable examples are optional inspiration. They are not mandates, required menus, or reasons to ask the user to choose again when the agent already knows the objective. If the user has asked for a clip, file, campaign, audit, or post package and the next action is safe and available, perform it directly.

## Platform Default

If the user does not name a destination, disclose and use Instagram Reels (`instagram_reels`) as the default. Search responses explicitly say whether this was assumed and return the preferred orientation, aspect ratio, and caption treatment.

Supported platform profiles:

- `instagram_reels`
- `instagram_feed`
- `tiktok`
- `youtube_shorts`
- `youtube`
- `facebook_reels`
- `facebook_feed`
- `linkedin`

## Reader Tools

### ee_clip_search

Find social clip candidates by topic, quote, guest, episode, language, speaker, claim, or transcript evidence. Returns transcript context, evidence quality, dimensions, orientation, duration, codecs, caption treatment, platform fit, grouped variants, review pointers, and download readiness.

Inputs:

- `query`: required plain-language intent.
- `platform`: destination profile; defaults to `instagram_reels` only when omitted.
- `limit`: 1-50, additionally bounded by token policy.
- `sort`: `relevance`, `clip_score`, `duration_shortest`, `duration_longest`, `episode_newest`, or `episode_oldest`.
- `group_variants`: defaults true; groups equivalent clean and burned-in-caption versions.
- `news_context`: optional dated public context supplied by the caller.
- `context_terms`: optional lexical expansion terms.
- `filters.episode_number`: exact episode number.
- `search_scope`: `both`, `clips`, or `episodes`.
- `filters.result_kind`: `clip` or `episode_passage`.
- `filters.language`: `en`, `es`, `both`, or `all`.
- `filters.asset_type`: `v1clip`, `v1clip_captioned`, `legacy_v0clip`, or `episode_passage`.
- `filters.caption_treatment`: `burned_in`, `clean`, or `unknown`.
- `filters.orientation`: `vertical`, `landscape`, `square`, or `unknown`.
- `filters.platform_compatible`: when true, excludes known-incompatible dimensions.
- `filters.downloadable`: require or exclude downloadable assets.
- `filters.min_text_quality`: `full_transcript` for transcript-backed results only.

### ee_clip_catalog_status

Inspect catalog generation time, deduplicated row counts, transcript/sidecar coverage, language coverage, caption coverage, download readiness, supported filters/sorts, platform profiles, and default platform.

### ee_clip_suggested_workflows

Rank the full workflow registry against the current user intent. Returns direct agent actions, decision points, loadbearing dependencies, optional examples, completion definitions, output contracts, and the next tool.

Inputs:

- `user_intent`: the latest explicit user objective already present in the conversation.
- `workflow_id`: optional exact route when the caller has already classified the task.
- `platform`: optional destination profile used for ranking.
- `language`: optional `en`, `es`, `both`, or `all` scope.
- `include_examples`: defaults true. Examples remain optional inspiration.

When `user_intent` is supplied, continue through `selection.next_tool`; do not merely repeat the selected workflow to the user unless they asked how the system works.

### ee_clip_asset_download

Resolve a selected `asset_id` into a native MCP resource link carrying a compact first-party, short-lived capability URI plus filename and MIME type. Dimensions and source-reported size remain in compact text metadata; exact rendition byte size is not asserted on the resource link. Media bytes and base64 are never embedded in model context, and the text block omits the capability URI. Desktop and mobile agents should open or save that resource. A host with Quicklinks or shortcuts should create one from the structured URI and return only the native action. Agents must not substitute the separate review/provenance URL. No user-supplied local download path is required on mobile. Readers can use the selected file but cannot upload, delete, modify, or publish anthology assets.

Inputs:

- `asset_id`: exact ID returned by search.
- `quality`: optional `original`, `high_quality`, or `efficient`.

## User-Facing Presentation And Link Contract

Do not dump raw tool JSON. Present a compact result shaped for the user's request:

- Search shortlist: title, episode, language, duration, dimensions/orientation, caption treatment, transcript excerpt, match rationale, and any platform assumption that affects use.
- Human pointer: label `review_url` as **Review source context** or **Review provenance**. It is not the downloadable media.
- Media delivery: call `ee_clip_asset_download`. It returns structured MCP content with `type: resource_link`, `name`, `mimeType`, and a compact first-party `uri`. The agent should surface that native resource, or create a host-native Quicklink/shortcut from it, without pasting the URI into prose.
- File-capable host: save the resource, verify it with a media probe, and return the verified file as a native attachment or clickable absolute local-file link.
- Mobile host: use the native resource link directly; do not ask the user for a local destination.
- Unsupported host: state that the host cannot render or save MCP resources and preserve the selected `asset_id` for a compatible client. Never substitute an unauthenticated review link.
- Context safety: never decode, print, or paste binary/base64 media into chat, logs, receipts, or model context. Never expose or expand the first-party capability URI or its resolved source URI in prose.

Authenticated REST callers receive a compact first-party capability URL from `POST /download`. Stream it directly to a file, verify the file, and do not log or display the URL.

### ee_clip_narrative_plan

Use after selecting a full-episode passage. It returns phrase-safe timestamp units, prompt-term matches, a recommended contiguous hook-to-payoff arc, and review questions. The agent must confirm context, speaker fidelity, claims, and the ending.

Inputs:

- `source_window_id`: exact passage ID from search.
- `prompt`: creative brief with hook, tension, nuance, payoff, audience, and exclusions.
- `editorial_title`: concise working title for filenames and metadata, not an on-video headline.
- `desired_seconds`: 15-96 seconds before silence removal.

### Owned production tools

- `ee_clip_production_spec`: bind selected units or exact timestamps to the production DAG.
- `ee_clip_production_job_create`: queue a durable production job for the automatic approved worker.
- `ee_clip_production_job_status`: inspect analysis, signed word/silence/face/layout artifacts, review, render, errors, and catalog intake.
- `ee_clip_contact_sheet_get`: return the portrait contact sheet as a native MCP image.
- `ee_clip_review_contact_sheet`: approve or request precise visual revisions. A revise decision can include structured source bounds, sampling density, layout mode, caption center, and caption-band height overrides.

Default production contract: 1080x1920 at 30 fps; no on-video headline, B-roll, or emoji; highlighted captions; scene-relative face-safe subtitle placement; one-face tracked crop; two-speaker stacked crop when both speakers are necessary; phrase-safe silence removal; contact-sheet approval before render. Completed jobs persist clean and captioned files, transcript, sidecars, and searchable catalog rows.

The queue consumer runs automatically on the approved operator machine. After creating a job, poll status until `review_ready`, inspect and approve or revise the contact sheet, then continue polling while the worker renders and completes intake. Do not ask the user to start an external worker and do not create a duplicate job merely because processing is asynchronous.

## Admin Tools

Only administrator tokens see these in `tools/list`:

- `ee_clip_access_list`: safe token-prefix and lifecycle inventory; never returns raw tokens.
- `ee_clip_access_mint`: issue reader, auditor, or admin access; the bearer is returned once.
- `ee_clip_access_revoke`: revoke an active token by ID or prefix; self-revocation is blocked.

## Suggested Workflows

The live `ee_clip_suggested_workflows` result is canonical and includes complete actions, gates, examples, and completion definitions. The registry currently includes:

### topic_to_clip_candidates

Find and rank one or more transcript-backed moments. Search both existing clips and full-episode passages, select the best result when the user asked for one, and route production when only a source passage fits.

### exact_asset_download

Resolve an already-selected language/caption/dimension variant, use the short-lived grant immediately, verify the media when the agent environment permits, and deliver the actual file.

### full_episode_to_owned_social_derivative

Search first, then plan phrase-safe units, create a production spec and durable job, review or revise the contact sheet, monitor render/intake, search-readback, and deliver the selected clean or captioned result.

### social_asset_to_post_package

Choose the platform-fit asset and create transcript-grounded hook, caption, description, CTA, and restrained hashtags. Keep speaker claims separate from independently verified fact.

### multi_clip_campaign_pack

Build a non-duplicative set with distinct narrative roles such as hook, explanation, practical application, counterpoint, and reflection. Do not count clean/captioned variants as separate ideas.

### spanish_or_bilingual_clip_search

Use `es` for Spanish-only work and `both` for paired coverage. Compare provenance, transcript quality, duration, and variants; identify missing counterparts rather than silently returning one language.

### quote_or_moment_recovery

Resolve remembered wording or an incomplete scene to the most likely source. Distinguish semantic matches from verbatim matches and return episode, speaker context, excerpt, and usable asset or source window.

### current_news_to_ee_context

Verify unstable external facts with dated sources, pass bounded context into archive search, and preserve the boundary between public-source facts and podcast testimony.

### coverage_and_freshness_audit

Check generation time and bounded coverage, then spot-check the requested language, episode, or asset class. Return the exact gap and repair route instead of a vague readiness claim.

### production_job_resume_or_repair

Read durable status before acting. The automatic approved worker advances queued, revision-requested, and approved jobs. Poll while processing, inspect at `review_ready`, repair narrow errors at `failed`, and search/download at `completed`; never ask the user to trigger the worker or duplicate a job merely because time has passed.

### asset_review_handoff

Package the exact asset, transcript evidence, media facts, fit rationale, and remaining review question so a person or agent can continue without guessing.

### access_lifecycle_admin

Administrator-only access inventory, least-privilege mint, one-time secret-store handoff, verification, and revocation. Never repeat raw bearer values in prose, logs, or committed files.

## Installation

Codex CLI, `~/.codex/config.toml`:

```toml
[mcp_servers.ee-content-atlas]
url = "https://agents.everythingsenergy.show/mcp"
bearer_token_env_var = "EE_CLIP_SEARCH_TOKEN"
```

Set `EE_CLIP_SEARCH_TOKEN` to the raw token value without a `Bearer ` prefix, then restart the Codex host. The ChatGPT desktop app, Codex CLI, and IDE extension share this Codex MCP configuration.

For an arbitrary environment-backed header instead of bearer-token shorthand:

```toml
[mcp_servers.example]
url = "https://example.com/mcp"
env_http_headers = { "X-API-Key" = "EXAMPLE_API_KEY" }
```

The mapped environment variable contains the full header value. Do not configure both a literal authorization header and `bearer_token_env_var` for the same credential.

Claude Desktop:

```json
{
  "mcpServers": {
    "ee-content-atlas": {
      "type": "http",
      "url": "https://agents.everythingsenergy.show/mcp",
      "headers": {
        "Authorization": "Bearer <CATALOG_READER_TOKEN>"
      }
    }
  }
}
```

ChatGPT desktop uses the Codex configuration above. ChatGPT on the web does not read local Codex config or local environment variables. Web use requires an approved hosted plugin/connector whose server-side secret configuration supplies the credential, or an OAuth-enabled MCP server. Never paste a bearer into a conversation.

Another connector with a managed secret-header field:

```text
Name: EE Content Atlas
Transport: HTTP MCP
URL: https://agents.everythingsenergy.show/mcp
Secret header: Authorization: Bearer <CATALOG_READER_TOKEN>
First action: tools/list, then ee_clip_suggested_workflows with the current user intent, then ee_clip_catalog_status when freshness or coverage matters.
```

## REST Example

```bash
curl -sS \
  -H "Authorization: Bearer $EE_CLIP_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "https://agents.everythingsenergy.show/search" \
  -d '{
    "query": "energy medicine evidence problem",
    "platform": "instagram_reels",
    "sort": "clip_score",
    "group_variants": true,
    "limit": 5,
    "filters": {
      "language": "en",
      "orientation": "vertical",
      "platform_compatible": true,
      "downloadable": true,
      "min_text_quality": "full_transcript"
    }
  }'
```

## Output Expectations

Return:

- query and platform assumptions;
- catalog generation time;
- applied filters and sort;
- clip and episode identity;
- language and evidence quality;
- dimensions, aspect ratio, orientation, duration, and codecs;
- caption treatment and grouped variant options;
- download readiness;
- match rationale and transcript excerpt;
- review pointer when present;
- remaining uncertainty.
- `agent_guidance_before` and `agent_guidance_after` surrounding the unchanged result fields.

## Boundaries

Search results are candidates, not final judgment.
Public factual claims require separate public-source verification.
Health-adjacent topics should resolve to source episodes and the show's disclaimer, not synthesized treatment claims.
Legal, reputational, or investigative use requires human review before publication.
Reader access cannot upload, delete, modify, or publish assets.
Never expose access keys, private service credentials, or resolved download URLs in chat, logs, or committed artifacts.