Serac

Two packages, and nothing else:

The two are meant to be used together. The server gives a model the ability to act on a ServiceNow instance; the skills give it the judgement to do so without breaking one — which update set to be in, why a Business Rule needs ES5, what to check before renaming a field.

Both work with any MCP client. Neither requires the Serac product.

Quick start

npm install -g @serac-labs/servicenow-mcp

Point your MCP client at the servicenow-mcp-stdio binary:

{
  "mcpServers": {
    "servicenow": {
      "command": "servicenow-mcp-stdio",
      "env": {
        "SNOW_INSTANCE_URL": "https://dev12345.service-now.com",
        "SNOW_CLIENT_ID": "…",
        "SNOW_CLIENT_SECRET": "…"
      }
    }
  }
}

Credentials come from an OAuth application registry entry on your instance (System OAuth > Application Registry). A developer instance from developer.servicenow.com is enough to try everything here.

The catalog is far larger than a context window, so tools are deferred by default: tools/list returns two meta-tools and the model widens its own surface as it works.

tool_search({query: "incident"})  → the matching tools, now enabled
tool_execute({tool: "snow_query_incidents", args: {query: "priority=1"}})

Set SNOW_LAZY_TOOLS=false to register the whole catalog up front instead. Full options, library usage and the multi-tenancy rules are in the package README.

Using the skills

A skill is a directory with a SKILL.md: YAML frontmatter naming the skill and the snow_* tools it expects, then prose. Nothing loads them automatically — a host decides which ones to put in front of the model. Copy the ones you want into your agent's skills directory, or read them from the package:

import { skillsRoot } from "@serac-labs/skills/root"

They are worth reading on their own, even without an agent involved. Start with es5-compliance, update-set-workflow or blast-radius.

Working on it

Requires Bun 1.3.14 — pinned in the root package.json packageManager field, which is also what CI installs.

bun install
bun typecheck          # tsgo across both packages
bun run test           # both suites: 168 MCP tests, 60 skills tests
bun run lint           # oxlint

Tests do not run from the repo root directly — run them per package, or through turbo with bun run test:

cd packages/servicenow-mcp && bun test
cd packages/skills && bun test

Adding a tool

Tools live in packages/servicenow-mcp/src/servicenow-mcp-unified/tools/<domain>/snow_<name>.ts, one file per tool, each exporting a toolDefinition and an executor. The registry is generated by walking that directory, so a new file in the right shape is a new tool — there is no central list to edit. Regenerate the published manifest afterwards:

bun run --cwd packages/servicenow-mcp generate:tools-json

Adding a skill

Create packages/skills/<name>/SKILL.md with frontmatter, then regenerate the embedded map:

bun run --cwd packages/skills generate

bun test in that package fails if the embedded map drifts from the tree, or if frontmatter names a tool the MCP server does not actually have. Both of those have shipped to users before.

Two files that are production, not build output

packages/servicenow-mcp/tools.json and packages/servicenow-mcp/sn-roles.manifest.json are committed generated files, and live services fetch them straight from main over raw.githubusercontent.com. They are published by being committed. Moving or renaming either one is a production change: the consumer has to be repointed and deployed first, and the old path removed in a separate commit afterwards. See the package README.

Releases

@serac-labs/servicenow-mcp publishes from .github/workflows/publish-mcp.yml — a manual workflow_dispatch, versioned from packages/servicenow-mcp/package.json and nothing else, with OIDC trusted publishing and signed provenance. Every PR that touches the package runs the same build, test and packaging gates without publishing, including one that copies the package out of the workspace entirely and proves it installs, builds and tests with no monorepo around it.

@serac-labs/skills is not on npm today. It is consumed from a checkout.

What used to be here

This repository was a fork of opencode carrying a terminal AI agent, a TUI, a desktop app and a web console. Twenty-five packages went; the two above remain. The @serac-labs/core CLI those packages built is discontinued — it stays installable on npm at its final version, but there are no further releases and no security fixes for it.

The ServiceNow work was always the part worth keeping, and it was the part buried deepest. It is now the whole repository.

One artifact of that era is deliberately still here: the install script at the repo root. Every CLI already installed in the world fetches that exact URL when it self-upgrades, and serac.build/install redirects to it. Deleting the file would pipe a GitHub 404 page into those users' shells. It stays until it is replaced with something that tells them what happened — do not tidy it away.

Contributing

Read CONTRIBUTING.md first — it is short. Every PR links an issue, and the code style rules are in AGENTS.md.

License

Apache License 2.0. See NOTICE for third-party attributions: this code's history begins in the MIT-licensed opencode project.