Skip to content

Contributing ​

NekoSearch is MIT-licensed. Start with the development environment and the repository's working agreements.

Choose the owning boundary ​

Use the Architecture Overview to locate the responsibility you are changing. Source-specific transformations belong in integrations; generic parsing and retrieval belong in the engine; public command behavior belongs in the CLI; tool schemas and presentation belong at the MCP boundary.

Keep changes focused. Avoid adding dependencies or abstractions unless they solve a concrete requirement. Production dependencies require confirmation unless highly consolidated, safe, and trusted under the repository's working agreements.

Preserve observable behavior ​

  • Validate external inputs and fail explicitly.
  • Keep source/version isolation and exact-selector behavior intact.
  • Preserve the read-only, offline serving boundary and protocol-only stdout.
  • Treat snapshot hashes, schema versions, and stored formats as compatibility boundaries.
  • Keep optional source installation separate from package installation and server startup.

Add behavior-focused coverage when changing domain behavior. Never weaken tests to hide a failure; investigate the underlying contract first.

Required validation ​

Run formatting first:

sh
pnpm format

Then run these in parallel, as required by AGENTS.md:

sh
pnpm lint
pnpm typecheck
pnpm test

The repository uses npm workspaces and package-lock.json for dependency installation. These pnpm invocations run the existing package scripts; they do not imply migrating dependency management to pnpm. Fix failures and rerun the affected checks. Report checks that could not be completed.

For website changes, also run:

sh
npm run docs:site:build
npm run docs:site:check

Review rendering, navigation, local search, links, assets, and both themes. Tests for the CLI do not verify browser presentation.

Documentation accuracy ​

Inspect implementation, public schemas/types, and relevant tests before describing behavior. Use current CLI forms and MCP catalog schemas. Validate examples with a temporary catalog rather than editing a contributor's real MCP registrations.

These pages describe NekoSearch itself. The repository's separate docs/mcp-protocol directory supplies bundled reference content; it is not the source directory for this website. Do not copy external framework documentation into the product site.

Share a change ​

Use a focused issue or pull request in rafaself/neko-search. Explain the concrete behavior change, why it matters, validation results, and any limitations. Follow the repository's conventional commit format and avoid including generated website output, personal catalog data, or credentials.

Local documentation. Explicit sources. Better context.