Skip to content

PLAN.md

Latest commit

 

History

History
260 lines (193 loc) · 11.1 KB

PLAN.md

File metadata and controls

260 lines (193 loc) · 11.1 KB

ateam-mcp — Master Plan

Goal

Ship a working MCP server that lets any AI assistant (ChatGPT, Claude, Cursor, Windsurf, VS Code, Gemini) build, validate, and deploy ADAS multi-agent solutions through natural conversation. End-to-end: a developer installs it, their AI reads the spec, builds a solution, deploys it, and it runs.

Completed

Phase 1 — Stdio transport ✅

  • Claude Code integration working
  • All 14 tools connected and responding
  • Full workflow tested: spec → validate → deploy → manage

Phase 2 — HTTP transport (ChatGPT) ✅

  • Streamable HTTP transport at mcp.ateam-ai.com
  • ChatGPT "Ateam" app created and working in Developer Mode
  • Fixed array schemas for ChatGPT's stricter validation

Phase 4 — npm publish ✅

  • @ateam-ai org created on npmjs.com
  • Published: @ateam-ai/mcp@0.1.3
  • Install: npx -y @ateam-ai/mcp

Phase 5 — Marketplaces ✅

Phase 7 — Infrastructure ✅

  • All services run on mac1 (Docker + launchd agents)
  • Cloudflare tunnel runs on mac1 directly
  • MCP HTTP server runs on mac1 as launchd agent
  • See "Infrastructure" section below for full details

Infrastructure — What's Running on mac1

Architecture

mac1 is the solution host. All backend services run there in Docker containers. The Cloudflare tunnel and MCP HTTP server run as native launchd agents on mac1.

Internet → Cloudflare → mac1 tunnel → localhost services
                                        ├── :3201 Skill Validator (Docker)
                                        ├── :4311 Skill Builder (Docker)
                                        ├── :4100 ADAS Core (Docker)
                                        └── :3101 MCP HTTP Server (native)

Services

Service How it runs What it does Port
Cloudflare Tunnel launchd com.cloudflare.cloudflared Routes api/mcp.ateam-ai.com → localhost —
MCP HTTP Server launchd com.ateam-ai.mcp-http Streamable HTTP MCP endpoint for ChatGPT 3101
Skill Validator Docker adas_mcp_toolbox_builder-backend-1 ADAS API (validates + stores skills) 3201
Skill Builder Docker (same container) Generates MCP servers from skill defs 4311
ADAS Core Docker ai-dev-assistant-backend-1 Runs agent solutions 4100

Commands (run via ssh mac1)

# Check launchd services
launchctl list | grep -E 'cloudflare|ateam'

# Check Docker containers
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

# Restart cloudflared
launchctl unload ~/Library/LaunchAgents/com.cloudflare.cloudflared.plist
launchctl load ~/Library/LaunchAgents/com.cloudflare.cloudflared.plist

# Restart MCP HTTP
launchctl unload ~/Library/LaunchAgents/com.ateam-ai.mcp-http.plist
launchctl load ~/Library/LaunchAgents/com.ateam-ai.mcp-http.plist

# View logs
tail -f /tmp/cloudflared.log
tail -f /tmp/ateam-mcp-http.log

Health checks

# ADAS API (Skill Validator)
curl https://api.ateam-ai.com/health

# MCP HTTP server
curl https://mcp.ateam-ai.com/health

File locations (on mac1)

What Path
MCP server code ~/Projects/ateam-mcp/
Cloudflare tunnel config ~/.cloudflared/config.yml
Cloudflare tunnel credentials ~/.cloudflared/f5642a85-*.json
cloudflared binary ~/bin/cloudflared
LaunchAgent plists ~/Library/LaunchAgents/com.cloudflare.cloudflared.plist, com.ateam-ai.mcp-http.plist

DNS / Domains

Domain Routes to Via
ateam-ai.com Lovable hosting DNS A record (185.158.133.1)
www.ateam-ai.com Lovable hosting DNS A record
api.ateam-ai.com mac1 localhost:3201 Cloudflare Tunnel
mcp.ateam-ai.com mac1 localhost:3101 Cloudflare Tunnel

npm / Registry

What Value
npm package @ateam-ai/mcp v0.1.3
npm org @ateam-ai
npm user ariekogan
MCP Registry name io.github.ariekogan/ateam-mcp
GitHub repo ariekogan/ateam-mcp (public)
Smithery ateam-ai/ateam — https://smithery.ai/servers/ateam-ai/ateam

🔴 URGENT — Do This Week

🟡 Action Items — Arie (manual, needs browser)

Community / Outreach

  • Reply to punkpeye on PR #2097 — He asked: (1) your MCP Discord username for server author flair, (2) claim server on Glama, (3) Dockerfile (done). Go to punkpeye/awesome-mcp-servers#2097
  • Join MCP Discord — Search "MCP Discord" or "Model Context Protocol Discord", join, then share your username with punkpeye
  • Claim server on Glama.ai — Go to https://glama.ai/mcp/servers → find ateam-mcp → click "Claim ownership" (glama.json is already in the repo)

Marketplace Submissions

ChatGPT

  • Publish ChatGPT app — Currently in Drafts. Go to ChatGPT Settings → Developer → Apps → Ateam → publish

GitHub Repo (done)

  • Make repo public — Done
  • Add topics — Done (mcp, model-context-protocol, ai-agents, multi-agent, adas, mcp-server)
  • Add Glama config — glama.json added to repo root
  • Add Dockerfile — Dockerfile added for Docker-based usage

🟢 Action Items — Claude (can do in next session)

Phase 3 — Polish & Harden

Goal: production-ready quality

  • 3.1 Error handling & user-friendly messages — timeouts, connection errors, HTTP status hints
  • 3.2 Tool descriptions tuning (test with multiple LLMs)
  • 3.3 Response formatting — large payload summarization (50k char cap), structured error messages

Phase 6 — Onboarding & Developer Experience

Goal: new developer goes from zero to deployed solution in under 10 minutes

  • 6.1 Quick-start guide for each platform (Claude, ChatGPT, Cursor)
  • 6.2 API key provisioning — Tenant-embedded keys ✅
    • Keys use format adas_<tenant>_<32hex> (tenant encoded in key itself)
    • Legacy adas_<32hex> still supported for backwards compat
    • Clients only need one value (API key) — no separate tenant header required
    • See "Tenant Provisioning" section below for full details
  • 6.3 Example prompts library (customer support, document processing, etc.)

Phase 7 — Infrastructure (remaining)

Goal: production reliability

  • 7.1 Run all services as launchd agents (auto-start, auto-restart)
  • 7.2 Uptime monitoring (health checks, alerts — UptimeRobot or similar)
  • 7.3 Plan migration to cloud deployment for production reliability
  • 7.4 Multi-tenant support ✅ — Full per-tenant isolation implemented (see "Tenant Provisioning" below)

Fleet — Local File Sync

  • Sync skill-vehicle-tracker.yaml — Updated on_max_iterations from finalize to escalate in both YAML and JS files

Tenant Provisioning — What's Done

Overview

Multi-tenant isolation is fully implemented across the Skill Builder stack. Each tenant gets its own data directory, API keys, LLM config, and skill/solution storage. A single API key is all a developer needs — tenant identity is embedded in the key itself.

Key Format

New:    adas_<tenant>_<32hex>    → tenant extracted from key automatically
Legacy: adas_<32hex>             → tenant from X-ADAS-TENANT header (backwards compat)

What Was Built

Layer What Key Files
Key generation generateKey() embeds current tenant into new keys agentApiKeyStore.js
Key parsing parseApiKey() extracts tenant from key format agentApiKeyStore.js, apiKeyAuth.js
Auth middleware Resolves tenant: key-embedded → header → default. Sets x-adas-tenant for downstream routes apiKeyAuth.js (skill-validator)
JWT forwarding When Skill Builder is embedded in ADAS Core, JWT from Core carries tenant identity apps/backend/
PAT auth Skill Builder UI sends PAT for standalone access, backend resolves tenant from it apps/backend/, apps/frontend/
Per-tenant LLM Each tenant can have its own llm.json with provider/model/key config apps/backend/
Per-tenant API keys Settings UI generates/manages API keys scoped to the current tenant apps/frontend/
Dynamic tenants Tenants created on-demand via _builder subdir + embedded mode support apps/backend/
Agent API modal Auto-opens via ?show=api-key URL param for onboarding flow apps/frontend/

Tenant resolution priority (auth middleware)

  1. Tenant embedded in API key (adas_<tenant>_<hex>)
  2. X-ADAS-TENANT header (legacy / fallback)
  3. SB_TENANT env var / default "main"

Auth exemptions (no key required)

  • GET /health — health check
  • GET /spec/* — spec/examples (must be public for ChatGPT/Claude discovery)
  • POST /validate/* — read-only validation (no side effects)

Related commits

  • 66cad3a — Tenant-embedded API keys and ateam-mcp server
  • 880ee4d — JWT multi-source auth and login/logout helpers
  • 65e2915 — PAT-based tenant auth for Skill Builder
  • abf5746 — Auto-open Agent API modal via ?show=api-key URL param
  • 0a323e7 — Dynamic tenants + _builder subdir + embedded mode
  • 6b797a7 — Per-tenant API keys in settings.json
  • bc73d26 — Align LLM key resolution with Core per-tenant llm.json

What's Left

  • Self-service signup page at app.ateam-ai.com (get-api-key flow with tenant creation)
  • Tenant admin dashboard (list tenants, usage stats)
  • Rate limiting per tenant
  • Tenant deletion / cleanup

Milestone Checklist

Milestone Status
M1: Works locally — Claude Code calls adas_deploy_solution → solution runs ✅ Done
M2: Works for ChatGPT — ChatGPT user pastes URL → deploys through chat ✅ Done
M3: Published on npm — npx @ateam-ai/mcp works anywhere ✅ Done
M4: Discoverable — Listed on MCP Registry + community directories ✅ Registry + Smithery + awesome-mcp-servers
M5: Self-service — New dev installs, gets key, deploys first solution < 10 min 🟡 In progress — tenant provisioning done, self-service signup remaining
⚡