Development - visubramaniam/vsp360-mcp GitHub Wiki

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.