# BLUEPRINT: StackMCP
# Version: 3.0.0
# URL: https://stackmcp.app
# Updated: 2026-05-19

## IDENTITY
name: StackMCP
tagline: Test your MCP server before agents do.
description: StackMCP is a deterministic test runner and monitoring tool for MCP
  (Model Context Protocol) servers. Developers building agent-compatible apps
  paste their MCP endpoint or npm package name and receive a per-tool pass/fail
  report validating the JSON-RPC 2.0 protocol contract — schema validity, tool
  invocation with minimal valid inputs, proper JSON-RPC error handling on bad
  inputs, transport detection (Streamable HTTP, SSE, stdio), and optional
  Blueprint Protocol compliance. The free tier is a one-time anonymous test;
  the paid tier provides scheduled monitoring with alerts. No LLMs are involved
  in the test itself — MCP is a defined protocol and the tests are reproducible.
  StackMCP is part of the Stack app family.
category: developer-tools
url: https://stackmcp.app
contact: support@stackmcp.app
public-routes: /, /test, /results/:testId, /pricing, /docs
auth-required-routes: /dashboard, /monitors, /monitors/:monitorId, /account

## AUTH
provider: firebase
methods:
  - email+password
  - google-oauth

### UI (email)
steps:
  1. NAVIGATE /sign-in
  2. INPUT [data-agent-id="auth-email"] <<user-email>>
  3. INPUT [data-agent-id="auth-password"] <<user-password>>
  4. CLICK [data-agent-id="auth-submit"]
  5. WAIT [data-agent-id="dashboard"] (max: 10s)

## ACCESS
preferred: api
last-resort: ui

## USER ROLES
anonymous:
  description: Unauthenticated visitor. May run a single free test from the
    public test runner. Test result is stored anonymously and accessible via
    a shareable URL.
  detection: request.auth == null
client:
  description: Authenticated user. May view their saved test history and
    configure monitors (free tier: 1 monitor, paid tier: unlimited).
  detection: request.auth != null

## TARGET AUDIENCE
primary:
  - Developers building MCP-compatible apps and tools
  - Indie founders shipping agent integrations
  - SaaS teams adding an MCP server to their existing API
pain-points:
  - No reliable way to test an MCP server before pointing an agent at it
  - "Wire it to Claude Desktop and hope" is the current debugging workflow
  - Silent failures (malformed JSON-RPC, missing schema fields) only show up
    in agent runs, far away from the actual cause
  - No monitoring layer — when a deployed MCP server breaks, agents fail
    quietly and you find out from a user

## CAPABILITY: run-mcp-test
name: Run a one-time MCP server test
description: Deterministic structural test of an MCP endpoint (HTTP/SSE) or
  npm package (stdio). Issues tools/list, validates the JSON-RPC 2.0 response
  shape, validates each declared tool's input schema, calls each tool with
  minimal valid inputs, verifies proper JSON-RPC errors on bad inputs, detects
  which transports the server supports (Streamable HTTP, SSE, stdio), and
  optionally fetches and validates {domain}/blueprint.txt against the discovered
  tool list. Returns a per-tool pass/fail report with specific failure reasons.
  No LLM is involved. Industry standard endpoint format: https://mcp.yourapp.com
auth-required: false
scope: read-only
input:
  - name: transport
    type: string
    required: true
    description: "http" for HTTP/SSE endpoints, "stdio" for npm packages
  - name: endpoint
    type: string
    required: false
    description: Full MCP endpoint URL (https://mcp.yourapp.com). Required when transport is "http".
  - name: packageName
    type: string
    required: false
    description: npm package name (e.g. imagcon-mcp). Required when transport is "stdio".
  - name: apiKey
    type: string
    required: false
    description: Bearer token or API key. Used in-memory only; never stored
      with the test result.
  - name: checkBlueprint
    type: boolean
    required: false
    description: When true, also fetches {origin}/blueprint.txt and reports
      blueprint compliance alongside structural results. HTTP only.
output:
  - type: json
    description: Test result document with per-tool pass/fail entries, total
      duration, detected transport, supported transports matrix, blueprint
      compliance section (if requested), and a stable testId for the shareable
      results URL.
### API
method: POST
endpoint: https://stackmcp-backend-346839503757.us-central1.run.app/api/stackmcp/test
body:
  transport: "http" | "stdio"
  endpoint: string (required if transport is "http")
  packageName: string (required if transport is "stdio")
  apiKey: string (optional)
  checkBlueprint: boolean (optional)
response:
  testId: string
  endpoint: string
  passed: boolean
  toolsListPassed: boolean
  toolResults: ToolResult[]
  detectedTransport: "streamable_http" | "sse" | "stdio" | null
  supportedTransports: { streamableHttp: boolean, sse: boolean, stdio: boolean }
  transportAdvisory: string (optional)
  blueprint: BlueprintCompliance (optional)
  createdAt: ISO-8601
  durationMs: number
### UI
steps:
  1. NAVIGATE /test
  2. SELECT [data-agent-id="transport-http"] or [data-agent-id="transport-stdio"]
  3. INPUT [data-agent-id="endpoint-input"] <<mcp-endpoint-url>>  (if http)
  4. INPUT [data-agent-id="package-input"] <<npm-package-name>>   (if stdio)
  5. INPUT [data-agent-id="apikey-input"] <<api-key>>             (optional)
  6. TOGGLE [data-agent-id="blueprint-check"]                     (optional)
  7. CLICK [data-agent-id="run-test-btn"]
  8. WAIT [data-agent-id="test-results"] (max: 60s)
  9. VERIFY selector_exists [data-agent-id="tool-result-row"]

## CAPABILITY: get-test-result
name: Load a saved test result by id
description: Fetch a previously-run test result for the shareable results
  page. Anonymous reads are allowed — the result page is public by design so
  developers can share proof their server passes.
auth-required: false
scope: read-only
input:
  - name: testId
    type: string
    required: true
    description: Test id returned from run-mcp-test
output:
  - type: json
    description: Same shape as run-mcp-test response
### API
method: GET
endpoint: https://stackmcp-backend-346839503757.us-central1.run.app/api/stackmcp/test/:testId
response:
  testId: string
  endpoint: string
  passed: boolean
  toolResults: ToolResult[]
  detectedTransport: "streamable_http" | "sse" | "stdio" | null
  supportedTransports: { streamableHttp: boolean, sse: boolean, stdio: boolean }
  blueprint: BlueprintCompliance (optional)
  createdAt: ISO-8601
### UI
steps:
  1. NAVIGATE /results/<testId>
  2. WAIT [data-agent-id="test-results"] (max: 10s)
  3. VERIFY selector_exists [data-agent-id="tool-result-row"]

## CAPABILITY: create-monitor
name: Create a scheduled MCP server monitor
description: Set up an automatic recurring test for an MCP endpoint. The backend
  runs the same structural test on a schedule and sends an email alert when the
  server status changes (passing → failing or recovering). Free tier: 1 monitor.
auth-required: true
scope: write
input:
  - name: name
    type: string
    required: true
    description: Human-readable name for the monitor
  - name: endpoint
    type: string
    required: true
    description: Full MCP endpoint URL to monitor
  - name: apiKey
    type: string
    required: false
    description: Bearer token. Stored encrypted, never returned in full.
  - name: intervalMinutes
    type: number
    required: true
    description: Check interval — 5, 15, 30, or 60
  - name: alertEmail
    type: string
    required: true
    description: Email address to notify on status changes
### API
method: POST
endpoint: https://stackmcp-backend-346839503757.us-central1.run.app/api/stackmcp/monitors
headers:
  Authorization: Bearer <<firebase-id-token>>
body:
  name: string
  endpoint: string
  apiKey: string (optional)
  intervalMinutes: 5 | 15 | 30 | 60
  alertEmail: string
response:
  monitorId: string
  status: "pending"
### UI
steps:
  1. NAVIGATE /monitors
  2. CLICK [data-agent-id="new-monitor-btn"]
  3. INPUT [data-agent-id="monitor-name"] <<name>>
  4. INPUT [data-agent-id="monitor-endpoint"] <<endpoint>>
  5. INPUT [data-agent-id="monitor-apikey"] <<api-key>> (optional)
  6. SELECT [data-agent-id="monitor-interval"] <<interval>>
  7. INPUT [data-agent-id="monitor-email"] <<email>>
  8. CLICK [data-agent-id="monitor-submit"]

## CAPABILITY: list-monitors
name: List all monitors for the authenticated user
description: Returns all monitors owned by the caller, including current status,
  last checked time, and interval. API keys are never returned in full — only
  the last 4 characters are exposed as a hint.
auth-required: true
scope: read-only
### API
method: GET
endpoint: https://stackmcp-backend-346839503757.us-central1.run.app/api/stackmcp/monitors
headers:
  Authorization: Bearer <<firebase-id-token>>
response:
  monitors: Monitor[]
### UI
steps:
  1. NAVIGATE /monitors
  2. WAIT [data-agent-id="monitor-list"] (max: 10s)