snow-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project status

A working MCP (Model Context Protocol) server exposing ServiceNow Table API operations. See README.md for the user-facing tool list and setup.

Commands

• uv sync — install/update dependencies from pyproject.toml
• uv add <package> — add a new dependency (updates pyproject.toml and the lockfile together; prefer this over hand-editing)
• uv run main.py — start the server over stdio (blocks, waiting for an MCP client); set MCP_TRANSPORT=http to serve over HTTP instead (see main.py in Architecture)
• uv run mcp dev main.py — launch the MCP Inspector against the server for interactive/manual testing
• uv run pytest — run the test suite in tests/ (see Testing below). There is no linter configured yet.

Ad-hoc verification against a real instance

The automated suite (below) never touches a real ServiceNow instance. To sanity-check behavior against the real thing, import server directly and call tools through FastMCP's tool manager:

uv run python -c "
import asyncio, server
async def main():
    print(await server.mcp.call_tool('list_incidents', {'limit': 3}))
    await server._client.aclose()
asyncio.run(main())
"

This exercises real HTTP calls against the instance configured in .env — treat it as a smoke test, not a substitute for the test suite.

Testing

tests/ holds the pytest suite. Two layers, both hitting a fake https://fake-instance.service-now.com — no real ServiceNow instance or network access required:

• tests/test_servicenow_client.py — unit tests calling ServiceNowClient methods directly (query-string construction, _raise_for_error on both non-2xx and HTTP-200-with-status:failure bodies).
• tests/test_server_tools.py — integration tests that drive the real FastMCP tool-dispatch path via an in-process MCP client (mcp.shared.memory.create_connected_server_and_client_session, wired to server.mcp over in-memory streams — no subprocess, no real network transport). This is what catches registration/wiring bugs that a direct ServiceNowClient unit test can't see (wrong tool name, wrong argument schema, ServiceNowError not surfacing as a tool error, etc).