test(fetch_tools): add MCP mock server for integration testing (#68)

Author: ryoppippi

.github/workflows/ci.yaml

@@ -46,6 +46,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          submodules: true
 
       - name: Setup Nix
         uses: ./.github/actions/setup-nix

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/stackone-ai-node"]
+	path = vendor/stackone-ai-node
+	url = https://github.com/StackOneHQ/stackone-ai-node.git

flake.nix

@@ -98,17 +98,31 @@
 
               # security
               gitleaks
+
+              # Node.js for MCP mock server
+              bun
+              pnpm_10
+              typescript-go
             ];
 
             shellHook = ''
               echo "StackOne AI Python SDK development environment"
 
-              # Install dependencies only if .venv is missing or uv.lock is newer
+              # Install Python dependencies only if .venv is missing or uv.lock is newer
               if [ ! -d .venv ] || [ uv.lock -nt .venv ]; then
-                echo "📦 Installing dependencies..."
+                echo "📦 Installing Python dependencies..."
                 uv sync --all-extras
               fi
 
+              # Install Node.js dependencies for MCP mock server (used in tests)
+              if [ -f vendor/stackone-ai-node/package.json ]; then
+                if [ ! -f vendor/stackone-ai-node/node_modules/.pnpm/lock.yaml ] || \
+                   [ vendor/stackone-ai-node/pnpm-lock.yaml -nt vendor/stackone-ai-node/node_modules/.pnpm/lock.yaml ]; then
+                  echo "📦 Installing MCP mock server dependencies..."
+                  (cd vendor/stackone-ai-node && pnpm install --frozen-lockfile)
+                fi
+              fi
+
               # Install git hooks
               ${config.pre-commit.installationScript}
             '';

pyproject.toml

@@ -69,6 +69,7 @@ asyncio_mode = "strict"
 asyncio_default_fixture_loop_scope = "function"
 markers = [
     "asyncio: mark test as async",
+    "integration: mark test as integration test requiring MCP mock server",
 ]
 
 [tool.ruff.lint.per-file-ignores]

tests/conftest.py

@@ -0,0 +1,116 @@
+"""Pytest configuration and fixtures for StackOne AI tests."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import subprocess
+import time
+from collections.abc import Generator
+from pathlib import Path
+
+import pytest
+
+
+def _find_free_port() -> int:
+    """Find a free port on localhost."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        return s.getsockname()[1]
+
+
+def _wait_for_server(host: str, port: int, timeout: float = 10.0) -> bool:
+    """Wait for a server to become available."""
+    start = time.time()
+    while time.time() - start < timeout:
+        try:
+            with socket.create_connection((host, port), timeout=1.0):
+                return True
+        except OSError:
+            time.sleep(0.1)
+    return False
+
+
+@pytest.fixture(scope="session")
+def mcp_mock_server() -> Generator[str, None, None]:
+    """
+    Start the Node MCP mock server for integration tests.
+
+    This fixture starts the Hono-based MCP mock server using bun,
+    importing from the stackone-ai-node submodule.
+
+    Requires: bun to be installed (via Nix flake).
+
+    Usage:
+        def test_mcp_integration(mcp_mock_server):
+            toolset = StackOneToolSet(
+                api_key="test-key",
+                base_url=mcp_mock_server,
+            )
+            tools = toolset.fetch_tools()
+    """
+    project_root = Path(__file__).parent.parent
+    serve_script = project_root / "tests" / "mocks" / "serve.ts"
+    vendor_dir = project_root / "vendor" / "stackone-ai-node"
+
+    if not serve_script.exists():
+        pytest.skip("MCP mock server script not found at tests/mocks/serve.ts")
+
+    if not vendor_dir.exists():
+        pytest.skip("stackone-ai-node submodule not found. Run 'git submodule update --init'")
+
+    # Check for bun runtime
+    bun_path = shutil.which("bun")
+    if not bun_path:
+        pytest.skip("bun not found. Install via Nix flake.")
+
+    port = _find_free_port()
+    base_url = f"http://localhost:{port}"
+
+    # Install dependencies if needed
+    node_modules = vendor_dir / "node_modules"
+    if not node_modules.exists():
+        subprocess.run(
+            [bun_path, "install"],
+            cwd=vendor_dir,
+            check=True,
+            capture_output=True,
+        )
+
+    # Start the server from project root
+    env = os.environ.copy()
+    env["PORT"] = str(port)
+
+    process = subprocess.Popen(
+        [bun_path, "run", str(serve_script)],
+        cwd=project_root,
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+    try:
+        # Wait for server to start
+        if not _wait_for_server("localhost", port, timeout=30.0):
+            stdout, stderr = process.communicate(timeout=5)
+            raise RuntimeError(
+                f"MCP mock server failed to start:\nstdout: {stdout.decode()}\nstderr: {stderr.decode()}"
+            )
+
+        yield base_url
+
+    finally:
+        process.terminate()
+        try:
+            process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait()
+
+
+@pytest.fixture
+def mcp_server_url(mcp_mock_server: str) -> str:
+    """Alias for mcp_mock_server for clearer test naming."""
+    return mcp_mock_server

tests/mocks/serve.ts

@@ -0,0 +1,131 @@
+/**
+ * Standalone HTTP server for MCP mock testing.
+ * Imports createMcpApp from stackone-ai-node vendor submodule.
+ *
+ * Usage:
+ *   bun run tests/mocks/serve.ts [port]
+ */
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import {
+  accountMcpTools,
+  createMcpApp,
+  defaultMcpTools,
+  exampleBamboohrTools,
+  mixedProviderTools,
+} from "../../vendor/stackone-ai-node/mocks/mcp-server";
+
+const port = parseInt(process.env.PORT || Bun.argv[2] || "8787", 10);
+
+// Create the MCP app with all test tool configurations
+const mcpApp = createMcpApp({
+  accountTools: {
+    default: defaultMcpTools,
+    acc1: accountMcpTools.acc1,
+    acc2: accountMcpTools.acc2,
+    acc3: accountMcpTools.acc3,
+    "test-account": accountMcpTools["test-account"],
+    mixed: mixedProviderTools,
+    "your-bamboohr-account-id": exampleBamboohrTools,
+    "your-stackone-account-id": exampleBamboohrTools,
+  },
+});
+
+// Create the main app with CORS and mount the MCP app
+const app = new Hono();
+
+// Add CORS for cross-origin requests
+app.use("/*", cors());
+
+// Health check endpoint
+app.get("/health", (c) => c.json({ status: "ok" }));
+
+// Mount the MCP app (handles /mcp endpoint)
+app.route("/", mcpApp);
+
+// RPC endpoint for tool execution
+app.post("/actions/rpc", async (c) => {
+  const authHeader = c.req.header("Authorization");
+  const accountIdHeader = c.req.header("x-account-id");
+
+  // Check for authentication
+  if (!authHeader || !authHeader.startsWith("Basic ")) {
+    return c.json(
+      { error: "Unauthorized", message: "Missing or invalid authorization header" },
+      401,
+    );
+  }
+
+  const body = (await c.req.json()) as {
+    action?: string;
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    path?: Record<string, string>;
+    query?: Record<string, string>;
+  };
+
+  // Validate action is provided
+  if (!body.action) {
+    return c.json({ error: "Bad Request", message: "Action is required" }, 400);
+  }
+
+  // Test action to verify x-account-id is sent as HTTP header
+  if (body.action === "test_account_id_header") {
+    return c.json({
+      data: {
+        httpHeader: accountIdHeader,
+        bodyHeader: body.headers?.["x-account-id"],
+      },
+    });
+  }
+
+  // Return mock response based on action
+  if (body.action === "bamboohr_get_employee") {
+    return c.json({
+      data: {
+        id: body.path?.id || "test-id",
+        name: "Test Employee",
+        ...body.body,
+      },
+    });
+  }
+
+  if (body.action === "bamboohr_list_employees") {
+    return c.json({
+      data: [
+        { id: "1", name: "Employee 1" },
+        { id: "2", name: "Employee 2" },
+      ],
+    });
+  }
+
+  if (body.action === "test_error_action") {
+    return c.json({ error: "Internal Server Error", message: "Test error response" }, 500);
+  }
+
+  // Default response for other actions
+  return c.json({
+    data: {
+      action: body.action,
+      received: {
+        body: body.body,
+        headers: body.headers,
+        path: body.path,
+        query: body.query,
+      },
+    },
+  });
+});
+
+console.log(`MCP Mock Server starting on port ${port}...`);
+
+export default {
+  port,
+  fetch: app.fetch,
+};
+
+console.log(`MCP Mock Server running at http://localhost:${port}`);
+console.log("Endpoints:");
+console.log(`  - GET  /health       - Health check`);
+console.log(`  - ALL  /mcp          - MCP protocol endpoint`);
+console.log(`  - POST /actions/rpc  - RPC execution endpoint`);