buildout-mcp: Instructions file for Codex

Buildout MCP - AI Agent Documentation

Project Overview

Buildout MCP is a Model Context Protocol (MCP) server that provides AI agents with access to Buildin.ai - a Notion-like knowledge base platform. The server exposes search capabilities and page content retrieval through standardized MCP interfaces.

Key Technologies:

• TypeScript with ES modules
• Node.js 24.x
• MCP SDK (@modelcontextprotocol/sdk)
• Buildin API SDK (buildin-api-sdk)
• Zod for schema validation

Project Structure

buildout-mcp/
├── src/
│   ├── app.ts                      # Main entry point, MCP server setup
│   ├── common/                     # Shared utilities and types
│   │   ├── types.ts                # Core type definitions
│   │   ├── blockFetcher.ts         # API data retrieval logic
│   │   ├── markdownRenderer.ts     # Block-to-markdown conversion
│   │   └── searchFormatter.ts      # Search result formatting
│   ├── tools/                      # MCP tool implementations
│   │   ├── getPageContent.ts       # Page content retrieval
│   │   └── search.ts               # Search functionality
│   └── prompts/                    # MCP prompt templates
│       └── instructions.ts         # LLM instruction prompts
├── dist/                           # Compiled output
├── package.json
├── tsconfig.json
└── AGENTS.md                       # This file

Architecture

Two-Phase Data Processing

The codebase follows a consistent two-phase pattern for data handling:

1. Phase 1 - Data Retrieval: Fetch and accumulate data from Buildin API
2. Phase 2 - Data Transformation: Convert accumulated data to output format

Example flow for page content:

pageId → fetchPageContent() → PageContent → renderPageToMarkdown() → string
         (blockFetcher.ts)                   (markdownRenderer.ts)

MCP Capabilities

Resource: buildin:///pages/{pageId}

Provides page content as markdown.

• URI Template: buildin:///pages/{pageId}
• MIME Type: text/markdown
• Handler: src/tools/getPageContent.ts