Codapult is designed to work well with AI coding agents and AI-native IDEs. The repository includes agent instructions, Cursor rules, and an MCP server that exposes project-aware tools, resources, and prompt templates.
What Is Included
| Capability | File or command | Purpose |
|---|---|---|
| Agent guide | AGENTS.md | Project structure, rules, patterns, security requirements, MCP overview |
| Claude guide | CLAUDE.md | Short entrypoint for Claude Code/Claude Desktop users |
| Gemini guide | GEMINI.md | Short entrypoint for Gemini CLI/IDE users |
| Cursor rules | .cursor/rules/*.mdc | Pattern-specific rules for API routes, DB, components, adapters, plugins, server actions |
| Cursor MCP config | .cursor/mcp.json | Preconfigured MCP server connection |
| MCP server | codapult mcp-server | Structured project access for compatible agents |
Supported Agents
| Agent or IDE | Recommended setup |
|---|---|
| Cursor | Use included .cursor/rules and .cursor/mcp.json |
| Claude Code | Read CLAUDE.md/AGENTS.md; connect MCP through stdio if supported by your environment |
| Claude Desktop | Add the Codapult MCP server to claude_desktop_config.json |
| Codex | Read AGENTS.md; use the MCP stdio command when MCP tools are available |
| Gemini CLI / Gemini Code Assist | Read GEMINI.md/AGENTS.md; use the MCP stdio command where supported |
| Windsurf and other MCP clients | Configure node ../codapult-cli/dist/index.js mcp-server as a stdio MCP server |
MCP Server
The MCP server ships with @codapult/cli and exposes:
- 19 tools for project status, database inspection, env validation, plugin management, code generation, checks, and deployment readiness.
- 6 resources: schema, app config,
AGENTS.md,.env.example, validation schemas, and navigation config. - 2 prompt templates for Codapult code review and schema design.
Build the CLI before using local MCP:
cd ../codapult-cli
pnpm install
pnpm build
Start the server:
node ../codapult-cli/dist/index.js mcp-server
Full reference: MCP Server.
Cursor
The project includes:
{
"mcpServers": {
"codapult": {
"command": "node",
"args": ["../codapult-cli/dist/index.js", "mcp-server"],
"cwd": "."
}
}
}
Open Cursor settings and verify the codapult MCP server is active.
Claude Desktop
Add a stdio server entry:
{
"mcpServers": {
"codapult": {
"command": "node",
"args": ["/absolute/path/to/codapult-cli/dist/index.js", "mcp-server"],
"cwd": "/absolute/path/to/codapult"
}
}
}
Agent-Safe Workflows
Ask agents to use Codapult MCP tools instead of guessing:
- "Run Codapult doctor and tell me what is misconfigured."
- "List all database tables and propose a schema for saved reports."
- "Generate a protected dashboard page for invoices."
- "Install the CRM plugin and show what files changed."
- "Check deployment readiness for Docker and Terraform."
The MCP server reads project files directly and returns structured results, which reduces stale context and copy-paste errors.
Guardrails for Agents
When prompting an agent, include these constraints:
- Follow
AGENTS.mdand.cursor/rules. - Use
@/imports and existing UI components. - Server components by default; add
'use client'only when browser state or effects are needed. - API route pattern: auth, rate limit, Zod validation, business logic, JSON response.
- Server actions must validate input, check permissions, and revalidate affected paths.
- Never expose secrets through
NEXT_PUBLIC_variables. - Keep modules removable and respect
codapult:prunemarkers.