SyncroNow AI MCPサーバー
コミット 2026年11月3日AIクライアントがServiceNowのスコープ済みアプリケーションのコードをプレーンファイルとして管理し、Gitによるバージョン管理や、メタデータおよび依存関係の分析を行えるようにします。
別名 IvanBBaev/syncrona
- スター
- 3
- ツール
- —
- ダウンロード数(30日間)
- —
- 最新バージョン
- —
- 最終コミット
- 2026年11月3日
- ライセンス
- GPL-3.0
SyncroNow AI MCPとは
AIクライアントがServiceNowのスコープ済みアプリケーションのコードをプレーンファイルとして管理し、Gitによるバージョン管理や、メタデータおよび依存関係の分析を行えるようにします。
プロジェクトのREADMEから生成された概要
SyncroNow AI MCP server について
syncronaは、モダンな開発ワークフローを通じてServiceNowのスコープ済みアプリケーションのコードを管理することを開発者に提供します。スコープ済みアプリケーションのコードを編集可能なプレーンファイルとしてローカルのプロジェクトフォルダにダウンロードすることで、Gitによるバージョン管理が可能になり、実際の差分(diff)、履歴、ブランチ、プルリクエストへのアクセスが実現します。これにより、本来はServiceNowインスタンス内にのみ存在するコードを、標準的なリポジトリ形式へと変換できます。
ユーザーは、ビルドパイプラインを通じて、TypeScript、Babel、WebpackなどのモダンなJavaScriptツールを開発プロセスに統合できます。このMCP serverは、Basic、OAuth (password, client credentials, JWT bearer)、APIキー、Bearerトークンを含むさまざまな認証方法をサポートしています。Node.js version 22.0以降が必要であり、WindowsユーザーはWSLの使用が必須となります。本システムは、AIクライアントからこれらの操作を直接実行するための63個のMCPツールを提供します。
できること
- 1ServiceNowコードのバージョン管理ServiceNowのソースコードをGitで追跡し、ブランチやプルリクエストを利用できるようにします。
- 2JavaScript開発の近代化TypeScriptやWebpackを使用して、ServiceNowのコードをビルドパイプラインで実行します。
- 3スコープ済みアプリケーションのファイル管理スコープ済みアプリケーションのコードを編集可能なプレーンファイルに変換し、操作を容易にします。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
設定
SN_INSTANCE_DEVSN_PASSWORD_DEVSN_USER_DEV
| 名前 | 説明 | 種類 |
|---|---|---|
| SN_INSTANCE_DEV | — | |
| SN_PASSWORD_DEV | — | |
| SN_USER_DEV | — |
自動チェック
実行日 2026年11月14日完全なレポート →まだ検証されていません。サーバーには80点のスコア、重大な問題がないこと、および検証に必要な十分なデータが必要です。 チェックの仕組み · 点数を上げるための改善点
- ソースリポジトリがリンクされており、アクセス可能ivanbbaev/syncrona is public and reachablegithub.com/ivanbbaev/syncrona ↗合格
- パッケージがこのリポジトリをソースとして指定未チェック
- ビルドの来歴 (Sigstore 証明)未チェック
- オープンソースライセンス (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-11-03github.com/ivanbbaev/syncrona ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していない未チェック
- パッケージおよびその依存関係に重大な勧告なし未チェック
- モデルへの隠れた指示がない0 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされている未チェック
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るSyncroNow AI
Built and maintained in my own time. If SyncroNow AI helps you or your team, a sponsorship keeps it moving — it directly funds new features, fixes and keeping pace with ServiceNow's REST surface.
Overview
SyncroNow AI is a tool for managing ServiceNow code in a more modern way. It allows you to:
- Store scoped app code in GitHub in an editable way.🐙 (Looking at you studio source control👀)
- Run your code through build pipelines that enable you to write modern JavaScript and use modern development tools such as TypeScript, Babel, and Webpack. 🎉
- Take control of your development process in ServiceNow! 💪
Because your scoped-app code is downloaded as plain, editable files in a project folder, SyncroNow AI is well suited for tracking your ServiceNow source code in Git — giving you real diffs, history, branches and pull requests over code that would otherwise live only inside the instance.
Coming from now-sdk? The ServiceNow SDK's everyday commands have a
syncronacounterpart:query,cicd,push --create/--prune,init --new, and the whole Fluent (.now.ts) toolchain throughsyncrona fluent(which drives@servicenow/sdkwhen you install it). See docs/MIGRATING_FROM_NOW_SDK.md for the command and environment-variable mapping and the honest list of what is not covered yet.push --create/--prune,init --new, the data-model sidecars,cicd run-suite/run-test,fluent installandquerywere verified against a live instance on 2026-10-13. Still covered only by mocked tests:cicd install/publish/rollback,fluent move-to-app, thesync_fluent_buildMCP tool and the composite data-model layout. Try those on a development instance first.
Project documentation
- docs/ARCHITECTURE.md — package graph, the two ServiceNow clients and their shared transport policy, push/manifest flows, MCP request pipeline, and the module contract for adding/removing CLI commands and MCP tool families (mermaid diagrams).
- docs/PRODUCT_STATE.md — what works today, phase history, known gaps and operating constraints.
- docs/MULTI_INSTANCE.md — credential precedence, instance profiles, the dev→prod workflow, and CI.
- docs/MONOREPO_GUIDE.md — multi-scope layout, per-scope vs shared config, and CI matrices.
- docs/PLUGIN_DEVELOPMENT.md — the plugin contract and how to write and wire your own build plugin.
- docs/BUSINESS_ANALYSIS.md — product vision, personas, value proposition, competitive positioning, KPIs, prioritized roadmap and risk register.
- docs/COMPARISON.md — SyncroNow AI vs ServiceNow native Git,
the ServiceNow SDK (
now-sdk/ Fluent), and update sets (one-page comparison). - docs/MIGRATING_FROM_NOW_SDK.md — coming
from the ServiceNow SDK (
now-sdk/ Fluent): command and environment-variable mapping, authentication differences, and what is not covered yet. - docs/ENTERPRISE_READINESS.md — what remains for a public 1.0 / enterprise release (done / scheduled / owner-gated).
- ROADMAP.md — shipped capabilities, what 1.0 closed, and what is still open past it (with owner-gated items called out).
- SECURITY.md — vulnerability reporting and data-handling.
- SUPPORT.md — getting help, diagnostics, support scope.
- docs/TROUBLESHOOTING.md — symptom → cause → fix index for auth, connectivity, proxy/TLS, manifest, watch-mode and MCP issues.
- CONTRIBUTING.md — dev setup, quality gates, conventions.
- CODE_OF_CONDUCT.md — community standards.
- packages/mcp-server/README.md — MCP server setup, tools, guardrails, and safety notes.
- docs/MCP_TOOLS.md — autogenerated API reference for all
63 MCP tools (parameters, safety flags; regenerated via
generate-tool-reference.js, drift-gated by its--checkmode). - packages/credential-store/README.md — the global encrypted credential store (AES-256-GCM at rest, key derivation) shared by the CLI and MCP server.
- packages/redaction/README.md — the shared secret-detection and redaction primitive: which key names and value shapes count as credentials, why detection fails closed, and what the redaction marker encodes.
- docs/VERSIONING.md — semver policy, lockstep releases, the MCP tool-contract stability promise, and the Node.js support window.
- CHANGELOG.md — notable changes per release.
Table of Contents
Installation
syncrona and all fifteen @syncrona/* packages are published on npm with build
provenance, so no build step is needed to use the CLI.
Global CLI quick start
npm i -g syncrona
syncrona login
syncrona init
Or without installing anything: npx syncrona init.
Install from source
For contributing, or to run an unreleased commit:
git clone https://github.com/IvanBBaev/syncrona
cd syncrona
npm ci
npm run build
# expose the CLI as `syncrona` on your PATH:
npm link --workspace syncrona
syncrona login
syncrona init
Prefer not to link globally? Run the built CLI directly from the repo with
node packages/core/dist/index.js <command>.
Requirements
In order to use SyncroNow AI, you will need:
- Node.js version 22.0 or later
⚠️ Windows users: WSL (Windows Subsystem for Linux) is currently required — native Windows is not yet supported.
- Install WSL with an Ubuntu distribution (Windows version 1903+; earlier versions are untested/not working)
- Run all
syncronacommands from inside the WSL shell- (Optional) Windows Terminal is recommended for proper text rendering
Native Windows support (PowerShell install, Windows Credential Manager) is on the roadmap.
ServiceNow compatibility: SyncroNow AI talks only to standard ServiceNow REST/Table APIs and needs nothing installed on the instance, so it is broadly release-agnostic. It is actively used against recent ServiceNow releases; a formal supported-version matrix is being established — if you hit a release-specific issue, please open an issue with your instance version.
Authentication: SyncroNow AI supports every inbound REST authentication method
ServiceNow offers, in both clients (CLI axios and the MCP server's native
fetch). Select the method explicitly with SN_AUTH_METHOD, or let it be inferred
for backward compatibility. Every auth variable also accepts a per-profile
_<PROFILE> suffix.
Method (SN_AUTH_METHOD) |
Required vars | Notes |
|---|---|---|
Basic — basic (default) |
SN_USER, SN_PASSWORD |
HTTP Basic over HTTPS. |
OAuth password — oauth-password |
SN_OAUTH_CLIENT_ID, SN_OAUTH_CLIENT_SECRET, SN_USER, SN_PASSWORD |
OAuth 2.0 Resource Owner Password grant; Bearer token from oauth_token.do, refreshed on expiry/401. |
OAuth client credentials — oauth-client-credentials |
SN_OAUTH_CLIENT_ID, SN_OAUTH_CLIENT_SECRET |
OAuth 2.0 Client Credentials grant — service-to-service, no user password (Tokyo+). |
OAuth JWT bearer — oauth-jwt-bearer |
SN_OAUTH_CLIENT_ID, SN_OAUTH_CLIENT_SECRET, SN_JWT_KEY |
OAuth 2.0 JWT Bearer grant. SN_JWT_KEY is a path to (or inline) RS256 private-key PEM; a fresh signed assertion is minted per token. Optional SN_JWT_KID / SN_JWT_ISS / SN_JWT_SUB / SN_JWT_AUD override the JWT header/claims (defaults derived from client id + user + instance). |
API key — api-key |
SN_API_KEY |
Inbound REST API Key sent as a header — default x-sn-apikey, override with SN_API_KEY_HEADER (Vancouver+). |
Bearer token — bearer |
SN_BEARER_TOKEN |
A pre-issued OAuth access token sent as Authorization: Bearer <token> (the counterpart of now-sdk's SN_SDK_SESSION_BEARER_TOKEN). Environment-only: never stored by syncrona login and never refreshed. When present it is inferred ahead of every other method. |
Without SN_AUTH_METHOD the method is inferred exactly as before — bearer when
SN_BEARER_TOKEN is set, then OAuth password when a client id/secret pair and
a password are present, otherwise Basic — so
existing setups keep working unchanged. An unrecognized value is an error
rather than a fallback: syncrona doctor reports Unknown SN_AUTH_METHOD "<value>"
and the MCP server refuses to start, so a typo can no longer resolve silently to a
different method. Use a dedicated least-privilege integration user.
An injected UI session (Fluent tier only). SN_SESSION_COOKIE (the session's
Cookie header) and SN_SESSION_TOKEN (its X-UserToken CSRF token) are the
counterparts of now-sdk's SN_SDK_SESSION_COOKIE / SN_SDK_SESSION_TOKEN. When
SN_SESSION_COOKIE is set, the fluent actions hand that session to the SDK as is,
ahead of the profile's method and without a login; a token without a cookie is an
error. It is not an auth method: every other command ignores it, and so does
fluent types --native, which uses the profile. Environment-only and un-suffixed:
syncrona login never stores it, clears a stale one from .env, and syncrona
never renews it — once the session expires, the action fails with the instance's 401.
Mutual TLS (client certificate) is orthogonal to the method above and combines
with any of them (or works alone): point SN_CLIENT_CERT and SN_CLIENT_KEY at
PEM files (plus SN_CLIENT_KEY_PASSPHRASE if the key is encrypted). It is applied
at the TLS layer in both the CLI and the MCP server.
syncrona login walks you through any of these interactively (method picker), or
runs non-interactively with flags — for example
syncrona login --auth-method api-key --api-key XXXX or
syncrona login --auth-method oauth-client-credentials --client-id … --client-secret ….
Secrets are kept in the encrypted global credential store; the JWT key and TLS
cert/key are referenced by path, never copied into it. See
SECURITY.md and docs/MULTI_INSTANCE.md.
Corporate proxies & custom TLS (G9): the CLI honors the standard
HTTPS_PROXY / HTTP_PROXY / NO_PROXY environment variables automatically, so
it works behind a corporate proxy with no extra configuration. For a corporate
or self-signed certificate authority, point SYNCRONA_CA_BUNDLE at a PEM CA
bundle (or set Node's built-in NODE_EXTRA_CA_CERTS, which also covers the MCP
server's native-fetch client, which ignores SYNCRONA_CA_BUNDLE). As a last resort for a throwaway test instance,
SYNCRONA_TLS_REJECT_UNAUTHORIZED=0 disables certificate verification — insecure,
never use it against a real instance.
Request timeout: every ServiceNow request the CLI makes (data path and OAuth
token endpoint alike) is bounded at 120 seconds. Raise or lower it with
SN_REQUEST_TIMEOUT in milliseconds — a large bulk download over a slow link may
need more, and 0 restores the old unbounded behaviour. An unparseable or
negative value falls back to the 120-second default rather than disabling the
timeout.
Request rate: each client (the CLI and the MCP server alike) sends at most 20
requests per second to an instance. Set SN_MAX_RPS to a whole number from 1 to
20 to go slower — on a shared or fragile instance, say. It can only lower the
cap: a value outside that range, or one that is not a whole number, stops the
command with an error rather than silently running at full rate. The MCP server
reads it from its own environment (the env block of the MCP client
configuration), not from the project .env.
Instructions
- Create a folder to store the scoped app code.
- In a terminal, run
npm initinside the newly created folder and follow the instructions to set up your node module. - Install
syncrona(nothing needs to be installed on the instance — the CLI works against the standard ServiceNow REST/Table APIs)
npm i -D syncrona
- Initialize your SyncroNow AI project
npx syncrona init
If your repository is a monorepo with many scoped apps under packages/, run SyncroNow AI from the specific scope directory, for example packages/cs. Each scope package should get its own .env, sync.config.js, and sync.manifest.json.
- Configure your project!
- OPTIONAL BUT HIGHLY RECOMMENDED Once your project is configured the way you like, you can commit and push it to a git repository for superior tracking and version control! Make sure to create a
.gitignorefile and ignorenode_modulesand.envbecause you really don't want those files in your repository. - Start dev mode and start working! Every time you save a file that is tracked by SyncroNow AI, it will be built with your ruleset and the result will be placed in ServiceNow!
npx syncrona dev
How does it work?
SyncroNow AI takes a two-pronged approach to managing your ServiceNow scoped app. Architecture, creation of records, deletion of records, metadata and other ServiceNow objects besides your actual source code will be managed normally. Your source code itself will be managed inside of your SyncroNow AI project.
SyncroNow AI MCPのよくある質問
ServiceNowインスタンスへのインストールは必要ですか?
いいえ、標準のServiceNow REST/Table APIと通信するだけなので、インスタンスへのローカルインストールは不要です。
Windowsネイティブ環境はサポートされていますか?
Windowsネイティブはまだサポートされていません。WindowsユーザーはWSL (Windows Subsystem for Linux) を使用する必要があります。