@posidev-community/ptai-mcp

Standalone CLI launcher for the PT Application Inspector MCP.

Publication identities

The public npm package and the MCP Registry entry intentionally use different identifiers:

server.json is the MCP Registry manifest. It describes how clients discover and launch the npm package; it is not read by the launcher at runtime.

Related MCP server: Throughline

Requirements

• Node.js 18 or newer

• A PT Application Inspector bundle installed in the platform-specific bundle directory

Usage

Install the package with npm and start the MCP:

npx @posidev-community/ptai-mcp start

The start command fails fast when the MCP is not installed. Download and install the analyzer bundle with:

npx @posidev-community/ptai-mcp install

Installation stops running analyzer processes, downloads the configured bundle, and unpacks it into the platform bundle directory. The production endpoint is checked first; development builds may be available only from the PT test endpoint. Agent configuration can then be managed with configure.

If one of the trusted PT installer endpoints presents an untrusted TLS certificate, the CLI asks for explicit confirmation before disabling certificate verification for that download only. In a trusted, non-interactive development environment the same choice can be supplied explicitly with PTAI_MCP_ALLOW_INSECURE_TLS=1:

PTAI_MCP_ALLOW_INSECURE_TLS=1 npx @posidev-community/ptai-mcp install

$env:PTAI_MCP_ALLOW_INSECURE_TLS = '1'
npx @posidev-community/ptai-mcp install

Do not set this variable for untrusted endpoints or routine production use.

Other commands:

npx @posidev-community/ptai-mcp configure
npx @posidev-community/ptai-mcp update
npx @posidev-community/ptai-mcp status
npx @posidev-community/ptai-mcp uninstall

configure offers separate MCP and hooks selections for Cursor, Claude Desktop, Claude Code, Windsurf, Kimi Code, Codex, Antigravity, Gemini CLI, and OpenCode. Existing JSON/JSONC/TOML settings, and unrelated hooks are preserved. Agent configuration is supported on Windows, macOS, and Linux. Only agents with a detected configuration directory are shown. MCP servers are selected first; the hooks step then lists only the selected agents that support hooks. Space toggles a selection and Enter confirms it. Deselecting an agent removes only the PTAI-owned entries from that agent's configuration. An empty selection is applied immediately without an additional confirmation prompt.

The same menu can generate a custom-agent setup guide at ~/.ptai-mcp/PT_AI_Custom_Agent_Setup.md and offer to open it. The guide contains MCP, hooks, and agent-rules examples for clients without a built-in adapter.

Additional arguments after start are passed directly to McpProxy:

npx @posidev-community/ptai-mcp start --stdio

The CLI also checks versions.json and warns when the installed bundle version differs from the bundle version expected by this package.

Bundle locations

The MCP executable is named McpProxy.exe on Windows and McpProxy on Linux/macOS.

Running locally

From the source tree

Install dependencies, build the CLI, and invoke the entry point directly:

npm ci
npm run build
node ./bin/ptai-mcp.js --help

Install the analyzer bundle before starting:

node ./bin/ptai-mcp.js install
node ./bin/ptai-mcp.js configure
node ./bin/ptai-mcp.js status
node ./bin/ptai-mcp.js start

On Windows PowerShell, the equivalent entry point is node .\bin\ptai-mcp.js.

From a local npm artifact

Build the publishable archive first:

npm run artifact

Use the filename printed by npm pack (the current version produces posidev-community-ptai-mcp-1.0.0.tgz):

npm exec --yes --package=./posidev-community-ptai-mcp-1.0.0.tgz -- ptai-mcp --help
npm exec --yes --package=./posidev-community-ptai-mcp-1.0.0.tgz -- ptai-mcp install
npm exec --yes --package=./posidev-community-ptai-mcp-1.0.0.tgz -- ptai-mcp configure
npm exec --yes --package=./posidev-community-ptai-mcp-1.0.0.tgz -- ptai-mcp status
npm exec --yes --package=./posidev-community-ptai-mcp-1.0.0.tgz -- ptai-mcp start

On Windows PowerShell, use the local path form:

npm exec --yes --package=.\posidev-community-ptai-mcp-1.0.0.tgz -- ptai-mcp --help

Agent configuration generated by configure uses the published package name via npx, so automatic agent startup through that configuration requires the package to be available in the npm registry.

Licensing

The source code of this npm package is licensed under the MIT License; see LICENSE.

The PT Application Inspector analyzer bundle downloaded by install and update, including McpProxy and accompanying components, is proprietary software and is not covered by the MIT License. Its use is subject to the applicable Positive Technologies license agreement. This package does not grant additional rights to use, modify, or redistribute that bundle.

Development

npm install
npm run build

Run the test suite with:

npm test

Run the suite with enforced coverage thresholds and generate the HTML report:

npm run test:coverage

Before publishing, run the complete release verification:

npm run verify

Build the publishable npm artifact locally:

npm run artifact

This runs the complete verification first and creates a .tgz package in the repository root. The generated archive is a release artifact and is ignored by Git.

Validate the packed artifact in a clean temporary npm installation:

npm run smoke:artifact

The package version is the single source of truth. server.json is synchronized from package.json during packing and checked by npm run verify. The manifest also checks that its MCP Registry name matches package.json.mcpName and that its npm package entry matches the package name and version.