mcp-tools-as-code

# MCP Tools as Code

Transform MCP servers from discrete tool invocations into typed TypeScript APIs that agents interact with programmatically. This approach dramatically reduces token usage and enables native control flow.

## The Problem

Traditional MCP tool usage has two inefficiencies:

1. **Context Overload**: Tool definitions occupy significant context window space. Agents connected to many servers process thousands of tokens before reading requests.

2. **Intermediate Result Duplication**: Data retrieved through tool calls traverses the model multiple times. A meeting transcript fetched, summarized, and stored means processing the transcript tokens repeatedly.

## The Solution

Present MCP servers as filesystem-organized code APIs. Agents discover, load, and use tools via native TypeScript instead of discrete tool calls.

**Before** (150,000+ tokens for a simple workflow):
```
1. Tool call: gdrive.getDocument → Model processes result
2. Tool call: summarize → Model processes result
3. Tool call: salesforce.updateRecord → Model processes result
```

**After** (2,000 tokens):
```typescript
const transcript = (await gdrive.getDocument({ documentId: 'abc123' })).content;
const summary = extractKeyPoints(transcript);
await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: summary }
});
```

## Architecture

### Directory Structure

```
servers/
├── {server-name}/
│   ├── index.ts          # Re-exports all tools
│   ├── types.ts          # Shared types and interfaces
│   ├── {tool-name}.ts    # Individual tool modules
│   └── README.md         # Server documentation
└── index.ts              # Server discovery/registry
```

### Tool Module Pattern

Each MCP tool becomes a typed TypeScript module:

```typescript
// servers/google-drive/getDocument.ts
import type { DocumentResult } from './types';

export interface GetDocumentInput {
  /** Google Drive document ID */
  documentId: string;
  /** Format to retri