# Elara Video Intelligence

**A private MCP integration that lets ChatGPT retrieve X posts through an authenticated Cloudflare backend and explain retrieval failures accurately.**

Built by [Julz7727](https://github.com/Julz7727). This portfolio snapshot documents the first working release: MCP `0.2.2-mcp.2` and backend `0.2.1-diagnostics.1`.

> The source is public for review. The deployed service remains private. Recruiters can inspect the implementation, tests, and design decisions without receiving access to the live service or its credentials.

## Why I built it

I wanted to use an X post as a structured source inside ChatGPT, with a clear distinction between retrieved evidence and what the assistant could actually conclude. A link alone did not provide the controlled retrieval and useful failure reporting I wanted.

The first milestone was an authenticated path from ChatGPT to the X API: post text, author details, public engagement metrics, and attached media metadata. Full-thread retrieval and multimedia understanding remain outside this release.

## What works

| Capability | Status |
| --- | --- |
| Private remote MCP connection using OAuth/OIDC | Verified |
| Owner-restricted access | Implemented and covered by identity tests |
| X post text, author details, public metrics, and media metadata | Live retrieval verified during the build |
| Authenticated backend configuration diagnostics | Verified again on November 4, 2026; no X request made |
| Distinct diagnostics for credentials, permissions, limits, availability, and network failures | Covered by mocked failure scenarios |
| Image-content analysis, sampled video frames, audio transcription | Not part of this release; v0.3 is paused |
| Full X thread/replies, Instagram, TikTok | Not supported |

The word **Video** in the project name describes the broader idea, not a capability claimed by this release. Returned media metadata is not image inspection, video viewing, or transcription.

## Architecture

```mermaid
flowchart LR
    U[Owner using ChatGPT] -->|OAuth authenticated MCP| M[MCP Worker]
    M <-->|OIDC identity verification| A[Cloudflare Access]
    M <-->|OAuth state| K[Workers KV]
    M -->|Service binding and shared backend key| B[Elara backend Worker]
    B -->|Bearer authenticated lookup| X[X API]
    X -->|Post data or failure| B
    B -->|Structured result and request ID| M
    M -->|Evidence with explicit limits| U
```

Two Workers keep the MCP authentication boundary separate from the X retrieval boundary. The X bearer token belongs only to the backend. The MCP Worker uses a direct service binding to reach that backend and still supplies the shared backend key.

## Tools exposed to ChatGPT

| Tool | Purpose | X API request? |
| --- | --- | --- |
| `evi_connection_status` | Check the authenticated MCP connection and version | No |
| `evi_backend_diagnostics` | Inspect endpoint settings and whether an X token is configured | No |
| `evi_retrieve_x_post` | Retrieve one public X post and its metadata | Yes; may consume X API credits |

Configuration diagnostics report credential presence, **not credential validity**. A successful live post retrieval is separate evidence that X authentication and access worked for that request.

## A failure that shaped the design

During integration, the backend responded correctly when accessed directly, but the MCP connector received HTTP 404. Changing communication between the Workers to an internal service binding resolved the issue.

This also exposed a reporting problem: a routing error must not become a claim that a post was deleted. The connector now separates its own failures, backend authentication, X API failures, and post-level availability. See [the engineering case study](docs/engineering-case-study.md).

## Security and reliability choices

- Owner identity checked in both the authorization flow and the MCP request handler.
- OIDC signature, issuer, audience, expiry, nonce, and required claims verified with `jose`.
- PKCE, browser-bound state, CSRF protection, and short-lived authorization state.
- Secrets entered through Cloudflare's secret management, with example-only public configuration.
- HTTPS X/Twitter URL allowlist; the backend constructs a fixed X API endpoint instead of fetching arbitrary user URLs.
- Redirects disabled on retrieval and token-exchange requests; bounded response bodies and timeouts.
- Allowlisted error classifications and request IDs rather than raw provider error details or credentials in diagnostics.
- Evidence flags remain false for video, transcript, and full-thread capabilities that were not executed.

These are implementation controls and test results, not a claim of an independent security audit. See [SECURITY.md](SECURITY.md) for scope and limitations.

## Explore the code

```text
packages/
  mcp/       MCP tools, OAuth/OIDC flow, service-binding client, tests
  backend/   Authenticated X retrieval and backend diagnostics
  shared/    Safe error classification and bounded JSON handling
docs/        Architecture decisions, verification record, and roadmap
examples/    Synthetic result payloads for reviewers
```

Start with [MCP tool definitions](packages/mcp/src/index.ts), [identity validation](packages/mcp/src/identity.ts), [the backend](packages/backend/src/index.mjs), and [diagnostic classification](packages/shared/diagnostics.mjs).

## Run checks without credentials or paid API requests

Requires Node.js 24.11 or later and npm.

```sh
npm --prefix packages/mcp ci
npm test
npm run type-check
npm run build
npm run check:public
```

`npm test` runs identity/security checks and 64 mocked diagnostic scenarios. `npm run build` is a deployment dry run using placeholder configuration; it does not publish a Worker. The public-content check is a lightweight repository guard, not a replacement for a dedicated secret scanner.

For a real deployment, follow [the setup instructions](docs/setup.md) and supply your own Cloudflare and X API configuration. No deployment automation in this repository targets the author's account.

## Evidence and honest limits

- On October 22, 2026, the owner verified a successful authenticated X post retrieval in ChatGPT, returning `X_POST_RETRIEVED`, HTTP 200, and post availability `available`.
- On November 4, 2026, the connected tools confirmed MCP `0.2.2-mcp.2` and backend `0.2.1-diagnostics.1`, with matching backend configuration and `xApiCalled: false`.
- The November check did not revalidate X credentials or retrieve another post.
- Examples in this repository are synthetic, labeled as such, and contain no real post text or live account settings.
- This edition replaces deployment-specific values with examples and omits the paused v0.3 implementation. It is not a byte-for-byte export of the live deployment.

## Skills demonstrated

TypeScript and JavaScript · Model Context Protocol · OAuth/OIDC · Cloudflare Workers and KV · service bindings · API integration · defensive error handling · automated testing · debugging distributed request paths.

I developed the project with AI assistance, adapting Cloudflare's MIT-licensed Access OAuth example and integrating the retrieval, access restrictions, diagnostics, and validation workflow. Upstream components are credited in [NOTICE.md](NOTICE.md).

## Roadmap

The verified milestone and paused work are recorded in [ROADMAP.md](ROADMAP.md) and the [public Project board](https://github.com/users/Julz7727/projects/1). v0.3 stays paused until explicitly resumed. Publishing this portfolio does not enable additional services or paid media processing.

## License

MIT, preserving the upstream Cloudflare notice. See [LICENSE](LICENSE).