test: add MCP mock server infrastructure

Add pytest fixtures and Hono-based MCP mock server for testing
fetch_tools against a real MCP protocol implementation:

- tests/conftest.py: Session-scoped fixture that starts bun server
  automatically when tests require mcp_mock_server
- tests/mocks/serve.ts: Standalone HTTP server importing createMcpApp
  from stackone-ai-node submodule, exposes /mcp and /actions/rpc

The server is started once per test session and provides the same
tool configurations as the Node SDK tests for consistency.

Author: ryoppippi

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,134 @@
+/**
+ * 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`);