Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
60 lines (39 loc) · 1.91 KB

CONTRIBUTING.md

File metadata and controls

60 lines (39 loc) · 1.91 KB
Raw

Contributing

Thanks for your interest in the Kosli MCP Server!

Getting started

git clone https://github.com/kosli-dev/mcp-server.git
cd mcp-server
npm install
npm run build
npm test

Development workflow

  1. Create a branch from main.
  2. Make your changes — run npm test and npm run build before pushing.
  3. Open a pull request against main.

Conventions

  • Commits and PR titles follow Conventional Commits (feat:, fix:, docs:, etc.).
  • TypeScript with strict: true. Relative imports use .js extensions (ESM).
  • Tests use Vitest. Run with npm test or npm run test:watch.

Architecture

The server exposes three tools — search_actions, execute_read_action, and execute_write_action — driven by a catalog generated from Kosli's OpenAPI spec. See CLAUDE.md for a detailed architecture overview.

Adding support for new Kosli API endpoints

In most cases, just regenerate the catalog:

npm run generate-catalog

The new endpoint becomes discoverable automatically. No code changes needed.

Testing the Claude Desktop extension locally

npm run pack:mcpb
open kosli-mcp-server-*.mcpb   # opens Claude Desktop install dialog

Versioning

You don't need to touch the version for an ordinary change — maintainers bump it when cutting a release. If you do, use npm version rather than editing package.json:

npm version patch --no-git-tag-version   # or minor / major

That updates package.json, package-lock.json, and the generated src/version.ts together. src/version.ts is generated by scripts/sync-version.mjs and should never be edited by hand; npm run sync-version repairs it if it drifts, and npm test fails when it does.

Releasing

Releases are automated via GitHub Actions. See the Releasing section in CLAUDE.md for the full procedure.