# BLUEPRINT: StackMCP [MCP]
# Version: 3.1.1
# URL: https://stackmcp.app
# Updated: 2026-05-21

## CAPABILITY: run-mcp-test
description: Deterministic structural test of an MCP endpoint (HTTP/SSE) or npm
  package (stdio). Issues tools/list, validates JSON-RPC 2.0 shape, validates each
  tool's input schema, calls each tool with minimal valid inputs, verifies JSON-RPC
  errors on bad inputs, detects supported transports (Streamable HTTP, SSE, stdio),
  and optionally fetches {origin}/.well-known/blueprint.txt against the discovered tool list.
  Returns a per-tool pass/fail report. No LLM involved.
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 for the target MCP server. Used in-memory only; never stored with the test result.
  - name: checkBlueprint
    type: boolean
    required: false
    description: When true, fetches {origin}/.well-known/blueprint.txt and reports blueprint compliance. HTTP only.
output:
  - type: json
    description: Test result with per-tool pass/fail, duration, detected transport,
      supported transports matrix, optional blueprint compliance, and testId for the shareable results URL.

### MCP
tool: run_test

### 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
description: Fetch a previously-run test result for the shareable results page.
  Anonymous reads are allowed — the result page is public 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

### MCP
tool: get_result

### 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
description: Set up a scheduled recurring test for an MCP endpoint. Runs the same
  structural test on a cron and emails on status changes. Requires StackMCP Pro.
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 for the monitored server. 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
output:
  - type: json
    description: monitorId and initial status

### MCP
tool: create_monitor

### 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
description: List all monitors for the authenticated user, including current status,
  last checked time, and interval. API keys are never returned in full.
auth-required: true
scope: read-only
output:
  - type: json
    description: Array of monitor records

### MCP
tool: list_monitors

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

## IDENTITY
name: StackMCP
description: Deterministic test runner and monitoring for MCP servers — validate JSON-RPC 2.0 compliance before agents connect.
category: developer-tools
contact: support@stackmcp.app

## SUMMARY
tagline: Test your MCP server before agents do.
audience: Developers building MCP-compatible apps who need reproducible protocol-level verification without wiring Claude Desktop.
capabilities:
  - run-mcp-test: Paste an endpoint or package and get a per-tool pass/fail report
  - get-test-result: Load a saved test by id for the shareable results page
  - create-monitor: Schedule recurring tests with email alerts (StackMCP Pro)
  - list-monitors: View all monitors and their current status (StackMCP Pro)

## AUTH
provider: firebase
methods: email, google-oauth

### UI
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)

## MCP
server: stackmcp
preferred-transport: streamable_http
install: Generate an API key at https://stackmcp.app/account and add the server to your MCP client config.
auth: STACKMCP_API_KEY — MCP API key issued from your StackMCP account

### TRANSPORT (streamable_http)
url: https://mcp.stackmcp.app
auth: bearer ${STACKMCP_API_KEY}

### REQUIRED-SECRETS
- STACKMCP_API_KEY:
    description: Your StackMCP API key for authenticated MCP tool calls (tools/call)
    obtain-at: https://stackmcp.app/account
    format: smcp_*

## ACCESS
preferred: mcp
fallback: api
last-resort: ui