osc-mcp: Instructions file for Codex

AGENTS.md — osc-mcp

Agent instructions for the osc-mcp codebase. Read this before writing any code.

---

Project Overview

An MCP (Model Context Protocol) server that bridges AI coding agents with the OpenCode SQLite database.

• opencodeDb — OpenCode's DB (~/.local/share/opencode/opencode.db). Read-only in practice.
• mcpDb — Our DB (~/.local/share/opencode/osc-mcp/mcp.db). We own schema and writes.

---

Commands (Bun only)

# Install dependencies
bun install

# Run all tests
bun test

# Run a single test file
bun test tests/storePreviousSessionContent.test.ts

# Run a specific test by name pattern
bun test --test-name-pattern "returns no previous session"

# Type-check (no emit)
bunx tsc --noEmit

# Run the MCP server
bun src/index.ts

• No dedicated lint/format command in this repo.
• Never use node, ts-node, npx, jest, or vitest. Always use bun/bunx.

---

Tool Catalog (src/index.ts)

Registered MCP tools:

• store_previous_session_content — stores filtered content for the most recent previous session.

• get_relevant_sessions — returns 10 most recent sessions (title, date, id) for a TOC.

• Input validation uses Zod schemas and zodToJsonSchema for tool manifests.

• CallToolRequestSchema parses args with Schema.parse(args || {}).

• Errors are returned as { content: [{ type: "text", text: Error: ... }], isError: true }.

---

Database Details (src/db.ts)

• Paths resolve to ~/.local/share/opencode/{opencode,osc-mcp/mcp}.db unless overridden by OPENCODE_DB / MCP_DB.
• PRAGMAs: busy_timeout=5000 on both DBs, journal_mode=WAL on mcpDb.
• Schema created on startup: mcp_session_summary(session_id TEXT PRIMARY KEY, project_id TEXT, content TEXT, time_created INTEGER, time_updated INTEGER).

---

Adding a New Tool

Every tool file must export:

1. A Zod schema named <ToolName>InputSchema
2. A type inferred from the schema
3. An async function implementing the tool

Then register it in src/index.ts:

• Add to the ListToolsRequestSchema handler's tools array
• Add a case in the CallToolRequestSchema switch