mcpengine/docs/CONTRIBUTING.md

# Contributing to MCPEngine

Thank you for your interest in contributing! This guide will help you add new MCP servers to the project.

## Adding a New Server

### 1. Check if it's needed

Before starting, check:
- Is there already an MCP server for this platform?
- Does the platform have a public API?
- Is there demand for this integration?

### 2. Set up the server structure

```bash
# Copy the template
cp -r servers/template servers/your-platform

cd servers/your-platform
```

### 3. Update package.json

```json
{
  "name": "@mcpengine/your-platform",
  "version": "1.0.0",
  "description": "MCP server for YourPlatform",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsc --watch"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0"
  }
}
```

### 4. Implement the server

Edit `src/index.ts`:

```typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

// API client setup
const API_KEY = process.env.YOURPLATFORM_API_KEY;
const API_BASE = 'https://api.yourplatform.com/v1';

// Create server instance
const server = new Server(
  {
    name: 'yourplatform-mcp-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'get_contacts',
        description: 'Get list of contacts',
        inputSchema: {
          type: 'object',
          properties: {
            limit: {
              type: 'number',
              description: 'Number of contacts to return',
            },
          },
        },
      },
      // Add more tools...
    ],
  };
});

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    case 'get_contacts': {
      const response = await fetch(`${API_BASE}/contacts?limit=${args.limit}`, {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
        },
      });
      const data = await response.json();
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(data, null, 2),
          },
        ],
      };
    }
    
    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('YourPlatform MCP server running on stdio');
}

main().catch((error) => {
  console.error('Server error:', error);
  process.exit(1);
});
```

### 5. Add a README

Create `servers/your-platform/README.md`:

```markdown
# YourPlatform MCP Server

MCP server for YourPlatform API integration.

## Setup

1. Get API key from [YourPlatform Dashboard](https://platform.com/settings)
2. Set environment variable:
   ```bash
   export YOURPLATFORM_API_KEY="your_key_here"
   ```

## Available Tools

- `get_contacts` — Retrieve contacts
- `create_contact` — Create new contact
- `get_deals` — List deals
- ... (list all tools)

## Usage with Claude Desktop

Add to `claude_desktop_config.json`:

\```json
{
  "mcpServers": {
    "yourplatform": {
      "command": "node",
      "args": ["/path/to/mcpengine/servers/yourplatform/dist/index.js"],
      "env": {
        "YOURPLATFORM_API_KEY": "your_key"
      }
    }
  }
}
\```
```

### 6. Build and test

```bash
npm install
npm run build
npm start
```

Test with Claude Desktop or another MCP client.

### 7. Create a landing page

Generate a marketing page:

```bash
cd landing-pages
node site-generator.js yourplatform
```

Edit `yourplatform.html` to customize.

### 8. Submit PR

```bash
git checkout -b feature/add-yourplatform-server
git add servers/yourplatform landing-pages/yourplatform.html
git commit -m "Add YourPlatform MCP server"
git push origin feature/add-yourplatform-server
```

Open a PR with:
- Description of the platform
- List of implemented tools
- Testing notes
- Any API limitations

## Code Style

- Use TypeScript
- Follow existing server patterns
- Add comprehensive error handling
- Include JSDoc comments for tools
- Keep API keys in environment variables

## Testing Checklist

- [ ] All tools work correctly
- [ ] Error handling for API failures
- [ ] Environment variables documented
- [ ] README includes setup instructions
- [ ] No hardcoded credentials
- [ ] TypeScript compiles without errors
- [ ] Tested with Claude Desktop

## Questions?

Open a [GitHub Discussion](https://github.com/yourusername/mcpengine/discussions) if you need help!