feat: add knowledge-graph and semantic-layer toolsets to OSS

[sunilgattupalle]

Summary

• Moves knowledge-graph toolset from mcpServerInternal to OSS: adds kg_queryable_type_summary, kg_grammar, and hql_query (validate/run execute actions)
• Moves semantic-layer toolset from mcpServerInternal to OSS: adds kg_type and kg_related_type
• Adds src/utils/strip-meta.ts shared utility (consolidates two identical inline copies)
• Adds harness_batch_validate_hql and harness_batch_execute_hql tools (parallel fan-out for HQL)
• Both toolsets are default-on; batch tools registered in registerAllTools()

Notes

• A corresponding cleanup PR in mcpServerInternal follows after this is published as 3.1.0
• Until the internal dep bump, mcpServerInternal keeps its own strip-meta.ts copy for data-connector.ts

Test plan

• pnpm typecheck passes
• pnpm test passes (1473/1473 tests)

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cursor]

Stale comment

Found 2 architecture-standard issues.

1. src/tools/index.ts:34 registers the new HQL batch tools outside the registry/toolset path. On the built branch, a HARNESS_TOOLSETS=logs registry still exposes harness_batch_validate_hql and harness_batch_execute_hql, so toolset filtering no longer matches the actual public surface.
2. README.md:11 still documents the 11-tool consolidated architecture, but this branch now publishes 13 tools and does not document the new HQL batch tools or the new knowledge-graph / semantic-layer surfaces in the README tables.

Assumptions:

• Treating the registry-backed generic-tool model and HARNESS_TOOLSETS filtering as intentional architecture constraints, per the repo guidance and README.

Change summary:

• Reviewed the PR diff, then verified with pnpm typecheck, pnpm build, pnpm docs:check, and a post-build tool-registration probe.

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

Stale comment

Found 3 issues that I think should be fixed before this PR is considered architecture-compliant:

1. High: src/tools/hql-batch.ts adds standalone HQL batch-tool code, but it is not wired into the live registration surface, so the file is dead code on the shipped MCP server and drifts from the repo's consolidated-tool / registry-backed design.
2. Medium: src/registry/toolsets/semantic-layer.ts advertises a kg_type.list contract that the extractor does not actually return, and it points agents at kg_queryable_type, which is not a registered resource type.
3. Medium: src/registry/toolsets/semantic-layer.ts relies on a dcs_enrichment list signal, but default harness_list compaction strips that key, so agents cannot see the signal the new docs describe.

Open questions / assumptions:

• Reviewed against live PR head ecd2018456156ca52a75073eae2812a6c2d34100.
• If src/tools/hql-batch.ts is intentionally staged for a follow-up, I would keep it out of this PR until it is either registry-backed or fully integrated and tested.

Verification:

• pnpm build
• pnpm exec vitest run tests/registry/registry.test.ts tests/tools/tool-handlers.test.ts
• Built-surface probe: HARNESS_TOOLSETS=logs still registers only the 11 consolidated tools (no harness_batch_* tools)
• Built runtime probe: compactItems([{..., dcs_enrichment: true}]) drops dcs_enrichment

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

registerHqlBatchTools() is never wired into registerAllTools() / server startup on the current head, so the two harness_batch_* tools never appear on the live MCP surface. That leaves this whole file as dead code in the OSS build and also drifts from the repo's documented 11-tool, registry-backed architecture. If HQL batching is meant to ship, it should either go through the existing registry / harness_execute path or be integrated and tested end-to-end; otherwise it should stay out of this PR.

[cursor]

This description is out of sync with the runtime contract in two ways: schemaTypesExtract() only returns summary fields (identifier, name, category, kind, description), not field metadata, and the HQL-oriented summary resource is kg_queryable_type_summary, not kg_queryable_type. Because harness_describe exposes this string directly, agents following it will both overestimate what kg_type.list returns and be pointed at a non-existent resource_type.

[cursor]

schemaTypesExtract() adds dcs_enrichment: true here, but default harness_list output immediately runs through compactItems(), and that whitelist drops dcs_enrichment. I verified on the built branch that compactItems([{..., dcs_enrichment: true}]) returns no dcs_enrichment key, so the signal this comment describes never reaches agents unless callers remember to set compact: false. If this flag is part of the agent contract, this resource needs skipCompact: true or the compact whitelist needs to preserve dcs_enrichment.

[cursor]

Found 3 issues that still keep this short of Sunil's architecture bar:

1. harness_execute batch HQL drops the first query's real response (and its per-query options), so the first item in every batch returns incomplete data.
2. The KG discovery hints advertise a harness_get call shape that the public tool doesn't accept (type_id / kind as top-level args instead of resource_id + params), so harness_describe is teaching agents a broken contract.
3. The new queries schema regresses the repo's Zod 4 metadata rule by calling .describe(...).optional(), which strips the description agents rely on.

Verification: pnpm install --frozen-lockfile, pnpm typecheck, pnpm build, pnpm test (1473 passing), plus stdio startup smoke tests with default toolsets and HARNESS_TOOLSETS=logs.

Residual risk: there is still no dedicated coverage for the new KG/semantic-layer resources or the batch execute path, so these issues were not exercised by the current suite.

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

This preflight call is executing the first query for real, but the response is discarded. The batch result later reports query 0 as just { query_string, success: true }, so the first item never returns its actual is_valid/errors or rows/columns/stats, and its timeout_ms / max_results are ignored as well. Can we capture and reuse this response (or do a non-executing preflight) before building results?

[cursor]

This hint doesn't match the public harness_get contract. The tool only accepts resource_id plus params, not top-level type_id / kind, so agents following this example will either fail validation or silently drop the fields. Can we switch the example to something like harness_get(resource_type='kg_type', resource_id='<identifier>', params={ kind: '<kind>' }) and update the similar description above as well?

[cursor]

Small standards issue: this uses .describe(...).optional(). Per the repo's Zod 4 rule in CLAUDE.md / AGENTS.md, .describe() needs to be last or the description is lost on the optional wrapper. This means agents won't actually see the queries guidance here. ...max(20).optional().describe(...) would preserve it.