Add structured MCP discovery and actionable tool contracts

[morluto]

Summary

• add a deterministic in-memory MCP evaluation suite with committed baseline transcripts and schema-legibility checks
• replace root intersection schemas with flat documented inputs and equivalent runtime validation
• add structured GitHub repository filters, an advanced raw_query escape hatch, concise and detailed pages, semantic references, query interpretation, warnings, and suggested actions
• return JSON error envelopes for agent-correctable requests and add polling hints to durable job references

The search contract keeps the deprecated query input and detailed response format as compatibility defaults. Repository search remains a bounded metadata-only GitHub read.

Evaluation decisions

The initial suite measures protocol calls, errors, response bytes, and polling calls through the real in-memory MCP transport. It does not claim model-selection or token-count results.

• Keep vectorized jobs.get: the baseline needs one submission and one poll, so it does not support consolidating job creation and polling.
• Add no search presets: structured filters are testable today, while trending or active presets need held-out model-backed or human-agent evidence and disclosed definitions.

This follows the tool-design principles in Writing tools for agents while keeping the changes within the existing MCP architecture.

Compatibility and safety

• Existing raw query calls continue to work and receive a deprecation warning.
• Detailed search output remains the default; concise output omits secondary repository facts.
• Conditional schema constraints moved to handlers because generated root allOf intersections rendered opaquely in some clients.
• Search persists repository metadata only and does not fetch code, execute repositories, or mutate GitHub.

Suggested review order

1. MCP contracts and errors in internal/mcpserver
2. Search compilation and response projection in internal/app
3. Evaluation fixtures, tests, and workflow documentation

Verification

• go test ./...
• go vet ./...
• go mod tidy -diff
• git diff --check

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.