mediagraph-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex when working with this repository.

Project Overview

Mediagraph MCP is a Model Context Protocol (MCP) server that provides AI assistants with access to the Mediagraph digital asset management API. It enables Codex and other MCP-compatible AI assistants to search, manage, and organize media assets.

Tech Stack:

• TypeScript with ESM modules
• Node.js 20+
• MCP SDK (@modelcontextprotocol/sdk)
• OAuth 2.0 with PKCE for authentication
• Vitest for testing
• tsup for bundling

Common Commands

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (watch)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type check without emitting
npm run typecheck

# Start the MCP server
npm start

Project Structure

src/
├── index.ts              # MCP server entry point, CLI handling
├── api/
│   ├── client.ts         # Mediagraph API client (all HTTP methods)
│   ├── types.ts          # Re-exports from types/
│   └── types/            # Split type definitions by domain
│       ├── index.ts      # Re-exports all types
│       ├── assets.ts     # Asset, SearchParams, etc.
│       ├── groups.ts     # Collection, Lightbox, StorageFolder
│       ├── tags.ts       # Tag, Taxonomy, etc.
│       ├── users.ts      # User, Organization, Membership
│       └── ...           # Other domain types
├── auth/
│   ├── oauth.ts          # OAuth flow with PKCE support
│   └── token-store.ts    # Encrypted token storage
├── tools/                # MCP tool definitions and handlers
│   ├── index.ts          # Combines all tool modules
│   ├── shared.ts         # Common types and helpers
│   ├── assets.ts         # Asset tools (search, get, update, etc.)
│   ├── groups.ts         # Collection, Lightbox, StorageFolder tools
│   ├── tags.ts           # Tag, Taxonomy tools
│   ├── admin.ts          # User groups, invites, uploads, etc.
│   └── ...               # Other tool modules
├── resources/            # MCP resource providers
│   └── index.ts          # mediagraph:// URI handlers
└── __tests__/            # Test files
    ├── tools.test.ts
    ├── types.test.ts
    └── client.test.ts