docs: restructure README and add client setup guide

[PatrickSys]

Summary

• README cut from 707 to ~220 lines — screenshots and CLI previews moved up, per-client setup blocks extracted, pipeline internals and eval harness moved to where they belong
• docs/client-setup.md (new) — all 7 client configs with stdio and HTTP variants, single-project fallback, local build testing instructions
• docs/capabilities.md — practical routing examples and selection_required response shape added (moved from README)
• CONTRIBUTING.md — eval harness section added (moved from README)
• templates/mcp/stdio/.mcp.json + templates/mcp/http/.mcp.json — copy-pasteable config templates shipped in the npm package
• tests/mcp-client-templates.test.ts — regression tests for template JSON validity and doc coverage
• package.json — docs/client-setup.md added to files array

Test plan

• pnpm test passes (344/344) — pre-push hook verified this
• README links resolve: docs/client-setup.md, docs/capabilities.md, docs/cli.md, template paths
• pnpm pack --dry-run includes docs/client-setup.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d8bdb1ad9f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use Node 18-safe path resolution in new test

This uses import.meta.dirname, which is not available on the minimum supported runtime (package.json declares "node": ">=18.0.0"), so the test module can throw at load time on Node 18 and fail vitest before any assertions run. Please switch to the same fileURLToPath(import.meta.url) + path.dirname(...) pattern already used in other tests to keep the suite compatible with the stated engine range.

Useful? React with 👍 / 👎.

[greptile-apps]

Greptile Summary

This PR restructures the documentation by trimming the README from ~707 to ~220 lines and extracting per-client setup, transport details, and eval harness content into focused destination files (docs/client-setup.md, docs/capabilities.md, CONTRIBUTING.md). Two copy-pasteable JSON templates are shipped in the npm package and backed by a new regression test suite.

Key changes:

• README.md — reduced to a quick-start overview with a compact transport-mode table and client-support matrix; all verbose setup blocks now live in docs/client-setup.md
• docs/client-setup.md — new file covering all 7 clients with stdio and HTTP variants, single-project fallback, and a local-build testing checklist
• docs/capabilities.md — Transport Modes section added; concrete routing examples and selection_required response shape moved here from README
• CONTRIBUTING.md — Evaluation Harness section added (moved from README)
• templates/mcp/stdio/.mcp.json + templates/mcp/http/.mcp.json — copy-pasteable templates now shipped in the npm package
• tests/mcp-client-templates.test.ts — regression tests for template JSON shape and doc reference coverage; the HTTP template test is missing a type: "http" assertion (see inline comment)

Confidence Score: 5/5

Safe to merge — documentation-only restructure with no behavioural code changes and a passing regression test suite.

All changes are documentation and static JSON templates. The one actionable finding (missing type assertion in the HTTP template test) is a test-coverage gap that does not affect runtime behaviour or user-facing correctness. The templates themselves are correct, the package.json files entry is right, and the doc cross-links are internally consistent.

tests/mcp-client-templates.test.ts — HTTP template test should also assert type: "http"

Important Files Changed

Filename	Overview
README.md	Cut from 707 to ~220 lines; per-client configs, CLI previews, pipeline internals, and eval harness all moved to dedicated docs; added compact transport-mode table and client-support matrix.
docs/client-setup.md	New file providing full per-client setup instructions for all 7 clients with stdio and HTTP variants, single-project fallback, and local-build testing checklist.
tests/mcp-client-templates.test.ts	New regression tests for template JSON validity and doc coverage; HTTP template test omits validation of the required type: "http" field.
docs/capabilities.md	Added Transport Modes section and concrete routing examples (monorepo subpath, repo path, file path) plus the selection_required response shape.
CONTRIBUTING.md	Eval harness section added (moved from README); includes offline smoke test command and report-saving instructions.
package.json	Added docs/client-setup.md and templates directory to the files array so both ship in the npm package.
templates/mcp/stdio/.mcp.json	New copy-pasteable stdio template; valid JSON with correct mcpServers shape and npx command.
templates/mcp/http/.mcp.json	New copy-pasteable HTTP template; valid JSON with type: "http" and correct local endpoint URL.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    README["README.md\n(quick-start + matrix)"]

    README -->|"Full per-client setup"| CS["docs/client-setup.md"]
    README -->|"Tool API + routing reference"| CAP["docs/capabilities.md"]
    README -->|"Dev setup + eval harness"| CONTRIB["CONTRIBUTING.md"]
    README -->|"CLI command gallery"| CLI["docs/cli.md (existing)"]

    CS -->|"Copy template"| STDIO["templates/mcp/stdio/.mcp.json"]
    CS -->|"Copy template"| HTTP["templates/mcp/http/.mcp.json"]

    STDIO -->|"Regression test"| TEST["tests/mcp-client-templates.test.ts"]
    HTTP -->|"Regression test"| TEST

    CAP -->|"doc-coverage test"| TEST
    README -->|"doc-coverage test"| TEST

    STDIO -->|"npm package (files[])"| PKG["package.json"]
    HTTP -->|"npm package (files[])"| PKG
    CS -->|"npm package (files[])"| PKG

Loading

_{Reviews (1): Last reviewed commit: "docs: restructure README and add client ..." | Re-trigger Greptile}

[greptile-apps]

Misleading "four target clients" comment

The it description says "covers all four target clients" but docs/client-setup.md covers seven clients (Claude Code, Claude Desktop, Cursor, Windsurf, Codex, VS Code, OpenCode). The test deliberately picks four, which is fine, but the wording will confuse a contributor who adds an eighth client and wonders why only four are checked.

Suggested change

	expect(readme).toContain('127.0.0.1:3100/mcp');
	});
	});
	// ---------------------------------------------------------------------------
	// docs/capabilities.md transport notes
	// ---------------------------------------------------------------------------
	it('covers core target clients', () => {
	expect(caps).toContain('Claude Code');
	expect(caps).toContain('Cursor');
	expect(caps).toContain('Codex');
	expect(caps).toContain('Windsurf');
	});