Framework Documentation

This documentation covers the technical architecture, design patterns, and implementation details of the Darbot Deepmind MCP Server.

Technical Stack

Core Technologies

Development Tools

Architecture Overview

Server Architecture

The Darbot Deepmind MCP Server implements a stateful reasoning engine with the following key components:

┌─────────────────────────────────────────┐
│         MCP Client (Claude/VS Code)     │
└──────────────────┬──────────────────────┘
                   │ MCP Protocol
                   │ (stdio transport)
┌──────────────────▼──────────────────────┐
│      DarbotDeepmindServer Instance      │
│  ┌────────────────────────────────────┐ │
│  │   Tool: darbot_deepmind            │ │
│  │   - Input Validation (Zod)         │ │
│  │   - Thought Processing             │ │
│  │   - History Management             │ │
│  │   - Branch Tracking                │ │
│  └────────────────────────────────────┘ │
│  ┌────────────────────────────────────┐ │
│  │   Thought History                  │ │
│  │   - Sequential storage             │ │
│  │   - Revision tracking              │ │
│  │   - Branch mapping                 │ │
│  └────────────────────────────────────┘ │
│  ┌────────────────────────────────────┐ │
│  │   Console Logger                   │ │
│  │   - Colored output (Chalk)         │ │
│  │   - Configurable verbosity         │ │
│  └────────────────────────────────────┘ │
└─────────────────────────────────────────┘

Design Patterns

1. Schema-First Validation

All inputs are validated using Zod schemas before processing:

const DeepmindSchema = z.object({
  thought: z.string().min(1),
  nextThoughtNeeded: z.boolean(),
  thoughtNumber: z.number().int().positive(),
  totalThoughts: z.number().int().positive(),
  isRevision: z.boolean().optional(),
  revisesThought: z.number().int().positive().optional(),
  branchFromThought: z.number().int().positive().optional(),
  branchId: z.string().optional(),
  needsMoreThoughts: z.boolean().optional(),
});

2. Stateful Reasoning Engine

The server maintains thought history to enable:

• Revision validation
• Branch tracking
• Context awareness
• Progress monitoring

3. Structured Response Format

Consistent JSON responses with metadata:

interface ThoughtResponse {
  thoughtNumber: number;
  totalThoughts: number;
  nextThoughtNeeded: boolean;
  branches: string[];
  thoughtHistoryLength: number;
  isRevision?: boolean;
  revisesThought?: number;
  branchId?: string;
  branchFromThought?: number;
  needsMoreThoughts?: boolean;
}

Core Concepts

Thought Processing

The framework processes thoughts through these stages:

1. Input Validation: Zod schema validation of all parameters
2. Revision Validation: Ensure revisions reference past thoughts
3. Branch Validation: Verify branch points are valid
4. Adaptive Planning: Adjust total thoughts dynamically
5. History Storage: Maintain ordered thought sequence
6. Response Generation: Create structured response with metadata
7. Console Logging: Format and display thought (if enabled)

Thought Revision

Revision mechanism allows reconsidering previous thoughts:

• Validation: Ensures revised thought exists and is in the past
• Context: Maintains connection to original thought
• Tracking: Records revision relationships in history

Branch Management

The framework supports exploring alternative solution paths:

• Branch Point: Any thought can be a branching point
• Branch ID: Unique identifier for each branch
• Parallel Exploration: Multiple branches can coexist
• Branch Tracking: Server maintains list of active branches

Adaptive Planning

Dynamic adjustment of thought count:

• Initial estimate can be adjusted up or down
• Automatic adjustment when thought number exceeds total
• needsMoreThoughts flag for explicit expansion
• No penalty for underestimation or overestimation

Implementation Details

Validation Logic

Three-tier validation ensures data integrity:

// 1. Schema Validation (Zod)
const validatedInput = DeepmindSchema.parse(input);

// 2. Revision Validation
if (validatedInput.isRevision) {
  if (!validatedInput.revisesThought) {
    throw new Error("revisesThought required when isRevision is true");
  }
  if (validatedInput.revisesThought >= validatedInput.thoughtNumber) {
    throw new Error("Can only revise past thoughts");
  }
}

// 3. Branch Validation
if (validatedInput.branchId && !validatedInput.branchFromThought) {
  throw new Error("branchFromThought required when branchId is set");
}

Thought History Management

Efficient in-memory storage with array-based history:

• Sequential append-only operations
• No deletions (immutable history)
• Fast access by index
• Branch tracking via separate set

Console Output Formatting

Colored, bordered output using Chalk and box-drawing characters:

┌─────────────────────────────────────┐
│ Thought 1/8                         │
├─────────────────────────────────────┤
│ Analyzing requirements for platform │
│ supporting 1M daily users           │
└─────────────────────────────────────┘

Performance Considerations

Memory Management

• Thought History: Grows linearly with reasoning depth
• Branch Set: Minimal memory overhead for tracking
• Recommendation: For very long chains (100+ thoughts), consider session breaks

Response Time

• Validation: O(1) - Constant time schema validation
• Processing: O(1) - No complex computations
• Formatting: O(n) where n is thought text length
• Typical: Sub-millisecond processing time

Concurrency

• Single-threaded Node.js event loop
• One reasoning chain per server instance
• Stateful design requires dedicated instances for parallel chains

Code Quality Standards

TypeScript Configuration

Strict mode enabled for type safety:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true
  }
}

Testing Requirements

• 80%+ code coverage minimum
• Unit tests for all validation logic
• Integration tests for MCP protocol
• Edge case testing (invalid inputs, boundary conditions)

Code Style

• ESLint with TypeScript rules
• Prettier for formatting (2 spaces, no tabs)
• JSDoc comments for public APIs
• Meaningful variable and function names

Build and Deployment

Build Process

# Install dependencies
npm ci

# Type checking
npx tsc --noEmit

# Build
npm run build

# Output: dist/index.js (transpiled JavaScript)

Docker Build

Multi-stage build for optimized images:

# Stage 1: Builder
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json tsconfig.json ./
RUN npm ci --only=production
COPY src ./src
RUN npm run build

# Stage 2: Runtime
FROM node:22-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER mcp
ENTRYPOINT ["node", "dist/index.js"]

CI/CD Pipeline

GitHub Actions workflow:

• Linting: ESLint checks on all commits
• Type Checking: TypeScript compilation without emit
• Testing: Jest with coverage reporting
• Build: TypeScript compilation and verification
• Docker: Image build and smoke test
• Coverage: Codecov integration for tracking

Extension Points

Custom Validators

Extend validation logic by adding custom validators:

validateCustomLogic(input: DeepmindInput): void {
  // Add custom validation rules
  if (input.thoughtNumber === 13 && input.branchId) {
    throw new Error("Branch not allowed at thought 13");
  }
}

Alternative Output Formats

Customize console output or add new output channels:

formatThought(input: DeepmindInput): string {
  // Custom formatting logic
  return `[${input.thoughtNumber}/${input.totalThoughts}] ${input.thought}`;
}

Best Practices

For Framework Users

• Start with conservative thought estimates
• Use revisions for significant insights
• Branch only when exploring truly different paths
• Keep thought descriptions concise but meaningful
• Monitor memory usage for very long chains

For Contributors

• Maintain backward compatibility for the tool API
• Add tests for all new functionality
• Document public APIs with JSDoc
• Follow existing code patterns and style
• Update documentation with changes

Next Steps