# ServiceNow PDI MCP Server

A TypeScript MCP stdio server that connects to a ServiceNow Personal Developer Instance with OAuth 2.0 and PKCE.

## Setup

1. Install Node.js 20 or newer.
2. Copy `.env.example` to `.env` and set the PDI URL, public OAuth client ID, redirect URI, and scope.
3. Ensure the ServiceNow OAuth application has this exact redirect URI: `http://127.0.0.1:33418`.
4. Run the one-time browser authorization flow:

```sh
npm run auth
```

Sign in to ServiceNow and approve the `useraccount` scope. The command exchanges the authorization code with PKCE and saves the refresh token to `.env`.
5. Install dependencies and compile:

```sh
npm install
npm run build
```

## MCP tool

`servicenow_test_connection` calls the ServiceNow Table API for `sys_properties` and returns up to 10 sample records. Its optional `limit` argument defaults to `1`.

The server requests tokens from `/oauth_token.do` using the saved refresh token. Public clients do not require a client secret.

## CRUD tools

Generic Table API tools work with any ServiceNow table:

- `servicenow_list_records` with `table`, optional encoded `query`, `fields`, and `limit`
- `servicenow_get_record` with `table` and `sysId`
- `servicenow_create_record` with `table` and a `fields` object
- `servicenow_update_record` with `table`, `sysId`, and a `fields` object
- `servicenow_delete_record` with `table` and `sysId`

Table names are restricted to letters, numbers, and underscores. ServiceNow ACLs still control which tables and fields the OAuth user can access.

Flow tools operate on the `sys_hub_flow` table and use `sys_id`:

- `servicenow_create_flow` with a `fields` object
- `servicenow_get_flow` with `sysId`
- `servicenow_update_flow` with `sysId` and a `fields` object
- `servicenow_delete_flow` with `sysId`

These operations use the ServiceNow Table API and require the OAuth user to have the corresponding table and field permissions.

Run the server directly with:

```sh
npm run dev
```

The VS Code MCP configuration is in `.vscode/mcp.json`. Open the MCP view, start `servicenow-pdi`, and invoke `servicenow_test_connection` after the environment variables are available to VS Code.

## Security

Do not commit `.env` or place credentials in `mcp.json`. The `.gitignore` file excludes `.env` and build output.

## References

- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP TypeScript SDK v2 documentation](https://ts.sdk.modelcontextprotocol.io/v2/)
- [ServiceNow Table API](https://www.servicenow.com/docs/bundle/xanadu-api-reference/page/integrate/inbound-rest/concept/c_TableAPI.html)
- [ServiceNow OAuth](https://www.servicenow.com/docs/bundle/xanadu-api-reference/page/integrate/inbound-rest/concept/c_OAuthAPI.html)