Development

For the architecture, the design decisions and how the components fit together, see Design.

Build and test

git clone https://github.com/visubramaniam/vsp360-mcp.git

cd vsp360-mcp && npm ci && npm test

npm test builds the TypeScript, runs the unit tests in tests/unit/ and then the search evaluation. The unit tests cover the HTTP client against a mock server, the spec loader, and the MCP server end to end, including the read-only and upload rules. The search evaluation fails if any score drops below its threshold. Tests need Node.js 22 or later.

Command	What it does
npm run build	Compile src/ to dist/
npm test	Build, unit tests, search evaluation
npm run eval	Search evaluation only, with detailed scores (EXAMPLES=0 to run without example questions)
npm run inspect	Open the MCP Inspector against the built server; needs the VSP360_* variables in your shell
npm run package	Build the release packages into release/ (see Releasing)

Code layout

Path	Contents
src/index.ts	MCP server: tools, read-only and secret rules, request handling
src/client.ts	HTTP client: sign-in, URL building, pagination, downloads, uploads, file-path rules
src/spec.ts	OpenAPI loader, read-only POST list, secret reads
src/search.ts	BM25 search, confidence rating
src/tools.ts	Tool definitions and input schemas
src/decision*.ts	Decision log and learned hint
spec/	OpenAPI spec, example questions, MQL field reference, decision model
tests/	Unit tests, search evaluation, labelled questions (user-queries.md)
scripts/package.mjs	Release packaging
packaging/mcpb/	Claude Desktop extension manifest

Contributing

• main is protected: open a pull request. CI runs the tests on Node.js 22 and 24, builds the npm and .mcpb packages, and runs CodeQL.
• Keep the history linear: rebase-merge or squash-merge.
• Never commit live VSP 360 data: names, serial numbers, WWNs, host names or IP addresses. Use placeholders in examples and tests. Stage files explicitly rather than with git add -A.
• Add a line to the Unreleased section of CHANGELOG.md for user-visible changes.

Improving search

These optional tools measure and improve how well search leads Claude to the right operation.

• Decision log (VSP360_DECISION_LOG): records locally, for each search, the query, the user's request (if Claude passes it), the confidence and the ranked results; for each describe or call, the operation, its rank in the latest search, the HTTP status and the duration. Argument values, bodies, headers and credentials are never logged, but treat the file like chat history.
• Collection mode (VSP360_DECISION_COLLECT=true): every question must produce a labelled search, and calls are refused unless the operation appeared in a recent search result. Use it for data-collection periods, with writes off.
• Batch collection: npm run collect-batch -- --part N sends one part of tests/user-queries.md to Claude through the API, one conversation per question. It needs ANTHROPIC_API_KEY (billed), skips held-out questions and resumes where it stopped. Its answers contain live VSP 360 data, so keep them out of git.
• Reports and training: npm run decision-report -- <log.jsonl> labels each search with what happened next; npm run train-decision trains the hint model and compares it with the confidence thresholds on held-out questions (--write saves it to spec/decision-model.json).

Adding a read-only POST

If VSP 360 adds a POST operation that only reads or validates, add its operationId to READ_ONLY_POSTS in src/spec.ts, update the read-only list in the README, and adjust the write-operation count in tests/unit/server.test.mjs. If it uploads a file, read-only mode will still require VSP360_UPLOAD_DIR for it.