# Contributing to MCPEngine

## RULE #1: Everything MCP goes here.

**This repository (`mcpengine-repo`) is the single source of truth for ALL MCP work.**

No exceptions. No "I'll push it later." No loose directories in the workspace.

---

## What belongs in this repo

### `servers/` — Every MCP server
- New MCP server? → `servers/{platform-name}/`
- MCP apps for a server? → `servers/{platform-name}/src/apps/`
- Server-specific tests? → `servers/{platform-name}/tests/`

### `infra/` — Factory infrastructure
- Testing tools (mcp-jest, mcp-validator, etc.) → `infra/factory-tools/`
- Pipeline state and operator config → `infra/command-center/`
- Review/eval reports → `infra/factory-reviews/`
- New factory tooling → `infra/{tool-name}/`

### `landing-pages/` — Marketing pages per server
### `deploy/` — Deploy-ready static site
### `docs/` — Research, reports, evaluations

---

## Commit rules

### When to commit
- **After building a new MCP server** — commit immediately
- **After adding/modifying tools in any server** — commit immediately
- **After building MCP apps (UI)** — commit immediately
- **After factory tool changes** — commit immediately
- **After pipeline state changes** — commit with daily backup
- **After landing page updates** — commit immediately

### Commit message format
```
{server-or-component}: {what changed}

Examples:
  closebot: Add 119 tools across 14 modules
  meta-ads: Fix campaign creation validation
  infra/factory-tools: Add watch mode to mcp-jest
  landing-pages: Update pricing on all 30 pages
  servers/new-platform: Scaffold new MCP server
```

### What NOT to commit
- `node_modules/` (already in .gitignore)
- `.venv/`, `venv/`, `__pycache__/`
- `.env` files with real API keys
- Large binary files (videos, images over 1MB)

---

## Adding a new MCP server

```bash
# 1. Create the directory
mkdir -p servers/my-platform

# 2. Build it (scaffold → tools → apps)

# 3. Commit and push
cd /path/to/mcpengine-repo
git add servers/my-platform/
git commit -m "my-platform: Scaffold new MCP server with N tools"
git push

# 4. Update pipeline state
# Edit infra/command-center/state.json to add the new server
```

---

## For Buba (agent rules)

**MANDATORY:** After ANY MCP-related work:
1. Copy/sync changes into `mcpengine-repo/` (correct subdirectory)
2. `git add -A && git commit -m "{descriptive message}" && git push`
3. Do NOT leave MCP work as loose directories in the workspace
4. If you build a new MCP server in workspace for speed, move it here when done
5. Update `infra/command-center/state.json` if pipeline stages change

**The workspace is scratch space. This repo is permanent.**

---

## Pipeline stages reference

| Stage | Name | Criteria |
|-------|------|----------|
| 1 | Identified | Platform selected, API docs reviewed |
| 5 | Scaffolded | Project compiles, basic structure |
| 6 | Core Tools Built | All API endpoints wrapped as tools |
| 7 | UI Apps Built | MCP Apps with visual UI |
| 8 | Integration Complete | Tools + Apps work together |
| 11 | Edge Case Testing | Error handling, rate limits, validation |
| 16 | Website Built | Landing page, docs, ready to deploy |

---

## Questions?

Ping Jake in #mcp-strategy or ask Buba.