Skip to main content
Glama

SpyNet

Session-based mock server for client application development with AI integration.

Features

  • REST API Mocking with sequential response support

  • WebSocket Support for both mock data and app control

  • Session Isolation for concurrent testing

  • MCP Integration for AI-driven development with Claude Desktop

Related MCP server: whistle-mcp

Quick Start

# Install dependencies
npm install

# Start server
npm run dev

# Server runs on http://localhost:8675 (default)
# Or configure with PORT=8080 npm run dev

Usage

Configure Mock Endpoint

curl -X POST http://localhost:8675/_mock/sessions/test-1/endpoints \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/api/users",
    "responses": [
      { "status": 200, "body": [{"id": 1, "name": "Test User"}] }
    ]
  }'

Request via Data Plane

curl http://localhost:8675/session/test-1/api/users
# Returns: [{"id": 1, "name": "Test User"}]

Send WebSocket Message

curl -X POST http://localhost:8675/_mock/sessions/test-1/socket/action \
  -H "Content-Type: application/json" \
  -d '{"action": "logout", "params": {"reason": "timeout"}}'

Using with Claude Desktop

SpyNet can be controlled by AI assistants via the Model Context Protocol (MCP).

Setup

  1. Build SpyNet:

    npm run build
  2. Add to Claude Desktop config:

    macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

    Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

    {
      "mcpServers": {
        "spynet": {
          "command": "node",
          "args": ["/absolute/path/to/spynet/dist/mcp.js"]
        }
      }
    }
  3. Restart Claude Desktop

Usage with Claude

Ask Claude to configure your mocks:

  • "Set up GET /api/users to return 3 test users"

  • "Configure login to fail first, then succeed"

  • "Send a WebSocket logout action to session demo"

  • "Show me the request history for session test-1"

Your app connects to http://localhost:8675 as usual.

Available MCP Tools

  • configure_endpoint - Set up mock API responses with sequential behavior

  • list_sessions - View all active sessions

  • delete_session - Clean up a session

  • list_endpoints - See configured endpoints and call counts

  • clear_endpoints - Remove mock configurations

  • get_request_history - Inspect request logs

  • send_websocket_action - Trigger app actions via WebSocket

  • send_websocket_data - Send real-time data via WebSocket

Troubleshooting

Check if SpyNet is running:

curl http://localhost:8675/_mock/sessions

View MCP server logs: MCP logs go to stderr. Check Claude Desktop's logs or run directly:

node dist/mcp.js

Port already in use:

# Check what's using port 8675
lsof -ti:8675

# Use different port
PORT=9000 node dist/mcp.js

Using with Claude Code

SpyNet can also be used with Claude Code (CLI) via MCP.

Setup

  1. Build SpyNet:

    npm run build
  2. Add to Claude Code:

    # Add for current user (stored in ~/.claude.json)
    claude mcp add --transport stdio spynet -- node /absolute/path/to/spynet/dist/mcp.js
    
    # Or add for your team (creates .mcp.json in project)
    cd /path/to/spynet
    claude mcp add --transport stdio spynet --scope project -- node ./dist/mcp.js
  3. Verify it's configured:

    claude mcp list

Usage

Same as Claude Desktop - just ask Claude to configure your mocks naturally:

  • "Set up GET /api/users to return 3 test users"

  • "Configure login to fail first, then succeed"

  • "Send a WebSocket logout action to session demo"

The same 8 MCP tools are available. Your app connects to http://localhost:8675 as usual.

API Reference

See Design Document for complete API documentation.

Development

# Run tests
npm test

# Build
npm run build

# Type check
npm run typecheck

License

MIT

Available Tools

8 tools
clear_endpointsC

Clear configured endpoints (all or specific)

Inputs: sessionId (required), method, path.

configure_endpointB

Configure a mock API endpoint with sequential responses

Inputs: sessionId (required), method (required), path (required), responses (required).

delete_sessionB

Delete a session and clean up resources

Inputs: sessionId (required).

get_request_historyC

Get request history for a session

Inputs: sessionId (required), limit.

list_endpointsB

List configured endpoints for a session

Inputs: sessionId (required).

list_sessionsB

List all active sessions with metadata

Inputs: no named parameters.

send_websocket_actionC

Send an action message to connected WebSocket client

Inputs: sessionId (required), action (required), params.

send_websocket_dataC

Send a data message to connected WebSocket client

Inputs: sessionId (required), data (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity: clear_endpoints, configure_endpoint, delete_session, get_request_history, list_endpoints, list_sessions, send_websocket_action, and send_websocket_data all target specific, non-overlapping operations in the mock API/WebSocket testing domain. The descriptions reinforce this clarity, making misselection unlikely.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, such as clear_endpoints, configure_endpoint, and list_sessions. This predictability aids agent understanding and selection, with no deviations in style or convention across the set.

    Tool Count5/5

    With 8 tools, the count is well-scoped for a mock API and WebSocket testing server. Each tool serves a distinct role in managing sessions, endpoints, and WebSocket communications, avoiding bloat while covering essential operations for the domain.

    Completeness4/5

    The tool set provides strong coverage for session and endpoint management, including CRUD-like operations (list, configure, clear, delete) and WebSocket messaging. A minor gap exists in not having tools for modifying existing endpoints or detailed session configuration, but agents can work around this with the available tools.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI to manage whistle mock rules, values, and inspect network sessions, facilitating API mocking and debugging through natural language.
      17
      8 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to dynamically add, update, and remove Mock Service Worker network handlers in a running browser app through a WebSocket bridge, without touching application source code or reloading the page. It also provides a setup prompt to scaffold the MSW and client integration in a project.
      15 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to dynamically add, update, and remove Mock Service Worker network mocks through MCP tools without restarting the application. It also supports scaffolding MSW setup and managing browser-connected mocking sessions via a WebSocket bridge.
      15 npm
      MIT