edstem-mcp: Instructions file for Codex

AGENTS.md

Operating manual for AI coding agents (Claude Code, Codex, Cursor, etc.) and new human contributors working on this repository.

Read this before making changes. It describes what this project is, how to run and test it, the conventions to follow, and the things never to do.

---

What this project is

edstem-mcp is a remote Model Context Protocol server that exposes the Ed Discussion (edstem.org) API as MCP tools, so any MCP-compatible client (claude.ai connector, Cursor, Claude Desktop, custom SDKs) can query and interact with EdStem on a user's behalf.

It is the network-deployed sibling of edstem-cli (a local Python CLI). The two are independent codebases; nothing is imported across them. When in doubt about EdStem API behaviour, consult edstem-cli/edstem_cli/client.py as the reference implementation.

The end-to-end implementation roadmap is in PLAN.md. Read that for the "where this is going."

---

Tech stack

• Runtime: Node.js >= 20
• Language: TypeScript (strict mode), ESM
• HTTP: Express 4
• MCP SDK: @modelcontextprotocol/sdk (^1.17)
• Schema validation: zod
• Tests: vitest
• Dev runner: tsx watch
• Database (planned, M1+): SQLite via better-sqlite3

No ORM. No framework beyond Express. Keep the dependency surface small.

---

Setup and common commands

npm install

# Required: an Ed API token from https://edstem.org/settings/api-tokens
export ED_API_TOKEN="your-ed-token"

npm run dev      # tsx watch on src/index.ts
npm run check    # tsc --noEmit, type-check only
npm run build    # compile to dist/
npm run start    # node dist/index.js (requires build first)
npm test         # vitest run

Server listens on http://localhost:8787/mcp by default.

Environment variables are documented in README.md and (for the planned multi-user mode) in PLAN.md §10.3.

---

Repository layout

src/
├─ index.ts              # Express bootstrap, route mounting
├─ config.ts             # env parsing and validation
├─ ed/                   # EdStem API client and domain types
│  ├─ client.ts          # HTTP client; Bearer auth; error mapping
│  ├─ models.ts          # TS types matching Ed JSON
│  ├─ serialization.ts   # to-MCP-payload converters
│  └─ filter.ts          # post-fetch filtering helpers
├─ mcp/
│  └─ server.ts          # MCP tool registry; one server per request
├─ oauth/                # OAuth 2.1 + PKCE provider for MCP auth
│  ├─ provider.ts        # EdstemOAuthProvider implementing OAuthServerProvider
│  ├─ store.ts           # FileOAuthStore (to be replaced by SQL store in M1)
│  ├─ session.ts         # signed cookie session for /authorize page
│  └─ login-page.ts      # HTML form rendering
test/                    # mirrors src/
dist/                    # build output (gitignored)
.data/                   # runtime state (gitignored)