# MCP Tool Wrappers - Usage Guide

This directory contains TypeScript wrappers for MCP tools using the code execution pattern from [Anthropic's blog post](https://www.anthropic.com/engineering/code-execution-with-mcp).

## Available Tools

### Basic Memory (Obsidian Vault Integration)

All tools are in `dist/servers/basic-memory/`

#### 1. writeNote
**Purpose**: Create or update notes in Obsidian vault

**Parameters**:
```typescript
{
  title: string;        // Note title
  content: string;      // Markdown content
  folder: string;       // e.g., "lockkey/agents/backend"
  project: string;      // e.g., "lockkey"
}
```

#### 2. readNote
**Purpose**: Read note contents

**Parameters**:
```typescript
{
  identifier: string;   // Note title or permalink
  project: string;      // e.g., "lockkey"
}
```

#### 3. editNote
**Purpose**: Append content to existing note

**Parameters**:
```typescript
{
  identifier: string;   // Note title or permalink
  content: string;      // Content to append
  project: string;      // e.g., "lockkey"
}
```

#### 4. deleteNote
**Purpose**: Delete a note

**Parameters**:
```typescript
{
  identifier: string;   // Note title or permalink
  project: string;      // e.g., "lockkey"
}
```

#### 5. moveNote
**Purpose**: Move note to new location

**Parameters**:
```typescript
{
  identifier: string;        // Note title or permalink
  destination_path: string;  // ⚠️ MUST include .md extension (e.g., "lockkey/testing/Note.md")
  project: string;           // e.g., "lockkey"
}
```

⚠️ **Common Mistakes**:
- Using `destinationPath` (camelCase) - it's `destination_path` (snake_case)
- Omitting the `.md` extension from destination_path

#### 6. searchNotes
**Purpose**: Search across knowledge base

**Parameters**:
```typescript
{
  query: string;        // Search query
  project: string;      // e.g., "lockkey"
}
```

⚠️ **Common Mistakes**:
- Adding extra parameters like `pageSize`, `page`, `searchType`, `types`, `entityTypes`, `afterDate` - these will cause validation errors

#### 7. listDirectory
**Purpose**: List directory contents

**Parameters**:
```typescript
{
  project: string;      // e.g., "lockkey"
}
```

⚠️ **Common Mistakes**:
- Adding parameters like `dirName`, `depth`, `fileNameGlob` - these will cause validation errors

## Usage Pattern

```typescript
import { executeAgentCode } from './dist/core/executor.js';

const code = `
import { resolve } from 'path';
import { pathToFileURL } from 'url';

// Set up tool directory
const toolsDir = resolve(process.cwd(), 'dist/servers/basic-memory');

// Import specific tool
const toolPath = pathToFileURL(resolve(toolsDir, 'writeNote.js')).href;
const { writeNote } = await import(toolPath);

// Call the tool
const result = await writeNote({
  title: 'My Note',
  content: '# Content',
  folder: 'lockkey/agents/backend',
  project: 'lockkey'
});

console.log(result);
`;

await executeAgentCode(code, { timeout: 15000 });
```

## Why Code Execution with MCP?

This pattern achieves **98.6% token savings** (50,000 → 700 tokens) through progressive disclosure:
- Load only the tools you need
- Tools discovered via filesystem exploration
- Intermediate results stay in execution environment
- Only final output passes through model context

## Troubleshooting

### "Unexpected keyword argument" Error
This means you're using a parameter the MCP server doesn't accept. Check this guide for the correct parameter list.

### Parameter Naming (snake_case vs camelCase)
The Basic Memory MCP server (Python) expects **snake_case** parameters:
- ✅ `destination_path`
- ❌ `destinationPath`

### TypeScript Compilation Errors
Run `npm run build` from the `backend/mcp-executor/` directory to rebuild the wrapper files.

## Adding New Tools

When adding new MCP tool wrappers:
1. Create TypeScript file in `src/servers/<server-name>/`
2. Follow the pattern from existing wrappers
3. Use `callMCPTool<ResponseType>('server__tool_name', input)`
4. Match parameter names exactly to what the MCP server expects
5. Document the tool in this file
