mcpengine/CONTRIBUTING.md

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

# 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.