# MCP Integration

Complete guide to integrating AIDP with Model Context Protocol (MCP).

## What is MCP?

Model Context Protocol (MCP) is an open standard for connecting AI assistants with external data sources and tools. Think of it as "USB-C for AI" - a universal way for AI platforms to access business data.

![MCP Protocol Flow](https://2687700396-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF8uzz8ItUjkBw81bmpg0%2Fuploads%2Fgit-blob-f033ade590671945e14a50f5acaa7b33b7c31789%2Fmcp-flow.svg?alt=media)

**Key Benefits**:

* ✅ Standardized protocol (works with Claude, ChatGPT, etc.)
* ✅ Secure and controlled access
* ✅ Real-time data updates
* ✅ Native AI integration

## Quick Start

### 1. Install MCP SDK

```bash
npm install @modelcontextprotocol/sdk @aidp-protocol/core
```

### 2. Create MCP Server

```typescript
import { MCPServer } from '@modelcontextprotocol/sdk';
import { AIDPToolCatalog } from '@aidp-protocol/core';

const server = new MCPServer({
  name: 'my-business-mcp-server',
  version: '1.0.0',
  description: 'MCP server for my business',
});

// Register AIDP standard tools
server.registerTools(AIDPToolCatalog.getStandardTools());

// Start server
server.listen(3000);
console.log('MCP server running on port 3000');
```

### 3. Test Your Server

```bash
# Test with MCP client
npx @modelcontextprotocol/inspector http://localhost:3000
```

## AIDP Standard Tools

AIDP Schema defines 8 standard MCP tools that all implementations should support:

### Discovery Tools

**search\_businesses**

```typescript
{
  name: 'search_businesses',
  description: 'Search for local businesses',
  parameters: {
    query: 'string (optional)',
    location: {
      city: 'string',
      country: 'string',
      coordinates: { lat: 'number', lon: 'number', radius: 'number' }
    },
    category: 'string (optional)',
    filters: {
      priceRange: 'string',
      rating: 'number',
      verified: 'boolean',
      openNow: 'boolean'
    }
  }
}
```

**get\_business\_details**

```typescript
{
  name: 'get_business_details',
  description: 'Get detailed business information',
  parameters: {
    businessId: 'string (required)',
    includeExclusiveContent: 'boolean (default: true)'
  }
}
```

**compare\_businesses**

```typescript
{
  name: 'compare_businesses',
  description: 'Compare multiple businesses side-by-side',
  parameters: {
    businessIds: 'string[] (2-5 businesses)',
    comparisonCriteria: 'string[] (optional)'
  }
}
```

### Booking Tools

**check\_availability**

```typescript
{
  name: 'check_availability',
  description: 'Check real-time availability',
  parameters: {
    businessId: 'string (required)',
    serviceId: 'string (required)',
    date: 'string (YYYY-MM-DD)',
    duration: 'number (minutes)',
    partySize: 'number'
  }
}
```

**create\_booking**

```typescript
{
  name: 'create_booking',
  description: 'Create a new booking',
  parameters: {
    businessId: 'string (required)',
    serviceId: 'string (required)',
    scheduledAt: 'string (ISO 8601)',
    customerInfo: {
      name: 'string',
      email: 'string',
      phone: 'string'
    },
    specialRequests: 'string (optional)'
  }
}
```

**submit\_lead**

```typescript
{
  name: 'submit_lead',
  description: 'Submit inquiry for quote-based services',
  parameters: {
    businessId: 'string (required)',
    serviceId: 'string (optional)',
    customerInfo: { ... },
    message: 'string (required)',
    urgency: 'low | medium | high'
  }
}
```

### Review Tools

**get\_reviews**

```typescript
{
  name: 'get_reviews',
  description: 'Get business reviews',
  parameters: {
    businessId: 'string (required)',
    filters: {
      rating: 'number',
      verified: 'boolean',
      hasPhotos: 'boolean'
    },
    sort: 'recent | helpful | rating_high | rating_low',
    limit: 'number (default: 10)'
  }
}
```

### Analytics Tools

**get\_upstream\_metrics**

```typescript
{
  name: 'get_upstream_metrics',
  description: 'Get upstream visibility metrics',
  parameters: {
    businessId: 'string (required)',
    startDate: 'string (YYYY-MM-DD)',
    endDate: 'string (YYYY-MM-DD)',
    metrics: 'string[] (impressions, citations, comparisons, zero_click)'
  }
}
```

[View complete tool catalog →](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/mcp-tools)

## Implementation Guide

### Step 1: Set Up Server

Create your MCP server with AIDP tools:

```typescript
import { MCPServer } from '@modelcontextprotocol/sdk';
import { AIDPClient } from '@aidp-protocol/core';

const aidpClient = new AIDPClient({
  apiKey: process.env.AIDP_API_KEY,
});

const server = new MCPServer({
  name: 'aidp-mcp-server',
  version: '1.0.0',
});

// Register search tool
server.registerTool({
  name: 'search_businesses',
  description: 'Search for local businesses',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string' },
      location: {
        type: 'object',
        properties: {
          city: { type: 'string' },
          country: { type: 'string' },
        },
        required: ['city', 'country'],
      },
    },
  },
  handler: async (params) => {
    const results = await aidpClient.businesses.search(params);
    return {
      businesses: results.businesses.map((b) => ({
        id: b.id,
        name: b.name,
        category: b.category,
        rating: b.trust.averageRating,
        location: b.location,
      })),
    };
  },
});
```

### Step 2: Implement Tool Handlers

Each tool needs a handler function:

```typescript
// Get business details
server.registerTool({
  name: 'get_business_details',
  description: 'Get detailed business information',
  parameters: {
    type: 'object',
    properties: {
      businessId: { type: 'string' },
      includeExclusiveContent: { type: 'boolean', default: true },
    },
    required: ['businessId'],
  },
  handler: async (params) => {
    const business = await aidpClient.businesses.getById(params.businessId, {
      includeExclusiveContent: params.includeExclusiveContent,
    });

    return {
      id: business.id,
      name: business.name,
      description: business.description,
      services: business.services,
      exclusiveContent: business.aiOptimization?.exclusiveContent,
      trust: business.trust,
    };
  },
});
```

### Step 3: Add Security

Implement authentication and rate limiting:

```typescript
import { RateLimiter } from '@aidp-protocol/core';

const rateLimiter = new RateLimiter({
  windowMs: 60000, // 1 minute
  maxRequests: 100,
});

server.use(async (req, res, next) => {
  // Verify API key
  const apiKey = req.headers['authorization']?.replace('Bearer ', '');
  if (!apiKey || !(await verifyApiKey(apiKey))) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Rate limiting
  const allowed = await rateLimiter.checkLimit(apiKey);
  if (!allowed) {
    return res.status(429).json({ error: 'Too many requests' });
  }

  next();
});
```

### Step 4: Deploy

Deploy your MCP server:

```bash
# Using Docker
docker build -t my-mcp-server .
docker run -p 3000:3000 my-mcp-server

# Using Node.js
npm start
```

## Testing Your MCP Server

### Using MCP Inspector

```bash
npx @modelcontextprotocol/inspector http://localhost:3000
```

### Using AIDP Validator

```bash
npm install -g @aidp-protocol/core

# Validate MCP server
aidp-validate mcp http://localhost:3000

# Check AIDP compliance
aidp-validate compliance --url http://localhost:3000
```

### Manual Testing

```typescript
import { MCPClient } from '@modelcontextprotocol/sdk';

const client = new MCPClient({
  serverUrl: 'http://localhost:3000',
});

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);

// Execute search
const result = await client.executeTool('search_businesses', {
  location: { city: 'Portland', country: 'USA' },
  category: 'restaurants',
});
console.log('Search results:', result);
```

## Best Practices

### Security

✅ **Do**:

* Validate all inputs
* Sanitize PII in responses
* Implement rate limiting
* Use HTTPS in production
* Rotate API keys regularly

❌ **Don't**:

* Expose internal errors
* Return sensitive data
* Allow unlimited requests
* Use HTTP in production
* Hardcode credentials

### Performance

✅ **Do**:

* Cache frequently accessed data
* Use connection pooling
* Implement pagination
* Monitor response times
* Set appropriate timeouts

❌ **Don't**:

* Make unnecessary database queries
* Return large payloads
* Block on slow operations
* Ignore memory leaks
* Skip error handling

### Tool Design

✅ **Do**:

* Keep tools focused and single-purpose
* Use clear, descriptive names
* Provide detailed descriptions
* Include usage examples
* Return structured data

❌ **Don't**:

* Create overly complex tools
* Use ambiguous names
* Skip documentation
* Return unstructured text
* Mix multiple concerns

## Advanced Topics

### Custom Tools

Add business-specific tools:

```typescript
server.registerTool({
  name: 'get_menu_specials',
  description: "Get today's menu specials",
  parameters: {
    type: 'object',
    properties: {
      date: { type: 'string', format: 'date' },
    },
  },
  handler: async (params) => {
    const specials = await getMenuSpecials(params.date);
    return { specials };
  },
});
```

### Webhooks

Notify AI platforms of updates:

```typescript
import { WebhookService } from '@aidp-protocol/core';

const webhooks = new WebhookService();

// Register webhook
await webhooks.register({
  url: 'https://ai-platform.com/webhooks/aidp',
  events: ['profile.updated', 'booking.created'],
});

// Trigger webhook
await webhooks.trigger('profile.updated', {
  businessId: 'biz_abc123',
  changes: ['description', 'hours'],
});
```

### Monitoring

Track MCP server performance:

```typescript
import { MCPMetrics } from '@aidp-protocol/core';

const metrics = new MCPMetrics();

server.use(async (req, res, next) => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    metrics.recordRequest({
      tool: req.body.tool,
      duration,
      status: res.statusCode,
    });
  });

  next();
});
```

## Troubleshooting

### Common Issues

**Tool not found**

```
Error: Tool 'search_businesses' not found
```

**Solution**: Ensure tool is registered with correct name

**Authentication failed**

```
Error: 401 Unauthorized
```

**Solution**: Check API key is valid and included in headers

**Rate limit exceeded**

```
Error: 429 Too Many Requests
```

**Solution**: Reduce request frequency or upgrade plan

**Timeout**

```
Error: Request timeout
```

**Solution**: Optimize slow queries, increase timeout, or use caching

## Examples

### Complete MCP Server

```typescript
import { MCPServer } from '@modelcontextprotocol/sdk';
import { AIDPClient } from '@aidp-protocol/core';
import { RateLimiter } from '@aidp-protocol/core';

const aidp = new AIDPClient({ apiKey: process.env.AIDP_API_KEY });
const rateLimiter = new RateLimiter({ maxRequests: 100, windowMs: 60000 });

const server = new MCPServer({
  name: 'aidp-mcp-server',
  version: '1.0.0',
});

// Middleware
server.use(async (req, res, next) => {
  const apiKey = req.headers['authorization']?.replace('Bearer ', '');
  if (!(await rateLimiter.checkLimit(apiKey))) {
    return res.status(429).json({ error: 'Too many requests' });
  }
  next();
});

// Register tools
server.registerTool({
  name: 'search_businesses',
  description: 'Search for local businesses',
  parameters: {
    /* ... */
  },
  handler: async (params) => {
    return await aidp.businesses.search(params);
  },
});

server.registerTool({
  name: 'get_business_details',
  description: 'Get detailed business information',
  parameters: {
    /* ... */
  },
  handler: async (params) => {
    return await aidp.businesses.getById(params.businessId);
  },
});

// Start server
server.listen(3000);
```

## Resources

* [MCP Specification](https://modelcontextprotocol.io)
* [AIDP MCP Tools](https://amistan.gitbook.io/aidp-docs/aidp-schema-open-standard/mcp-tools)
* [Code Examples](https://amistan.gitbook.io/aidp-docs/for-developers/examples)
* [Testing Guide](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/testing)

## Next Steps

* [Set Up MCP Server](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/setup)
* [Standard Tools](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/tools)
* [Custom Tools](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/custom-tools)
* [Testing](https://amistan.gitbook.io/aidp-docs/for-developers/mcp-integration/testing)