Add schema discovery command and read-only MCP tool (#160) - #184
Open
Mike Krüger (mkrueger) wants to merge 2 commits into
Open
Add schema discovery command and read-only MCP tool (#160)#184Mike Krüger (mkrueger) wants to merge 2 commits into
Mike Krüger (mkrueger) wants to merge 2 commits into
Conversation
Add a read-only 'schema' command that infers a container's structure from a bounded sample: partition key path(s), indexing policy summary, estimated document count, and inferred field types (dot notation for nested objects, per-field presence and observed JSON types). --sample selects the sample size (clamped to 1-100, default 20); --database/--container override the target. Exposed as a read-only MCP tool. Includes localization keys, docs (README, docs/commands.md), CHANGELOG entry, and unit tests for the sample-clamping and type-inference helpers.
Mike Krüger (mkrueger)
requested review from
a team
and
a lite review from Copilot
July 20, 2026 11:00
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
Comment on lines
+145
to
+149
| foreach (var text in json) | ||
| { | ||
| using var document = JsonDocument.Parse(text); | ||
| documents.Add(document.RootElement.Clone()); | ||
| } |
Code Coverage OverviewLanguages: C# C# / code-coverage/dotnetThe overall line coverage in commit e5de509 in the Show a line coverage summary of the most impacted files.
Updated |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a new schema discovery command (and matching read-only MCP tool) to provide a bounded, structured JSON summary of a Cosmos DB container—partition key paths, indexing policy summary, estimated document count, and inferred field types from a small sample—supporting agentic workflows that need fast, low-risk container introspection.
Changes:
- Introduces
SchemaCommandwith bounded sampling (--sampleclamped to 1–100) and JSON schema inference (dot-notation paths + type sets + per-field presence). - Adds unit tests covering sample clamping and schema/type inference helpers.
- Updates user-facing docs/help text (README,
docs/commands.md, localization strings, CHANGELOG).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds schema to the feature list and describes its discovery output at a high level. |
| docs/commands.md | Documents schema usage, options, examples, and sample output JSON. |
| CosmosDBShell/lang/en.ftl | Adds localized descriptions for the schema command and its options. |
| CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/SchemaCommand.cs | Implements the new schema command and MCP annotation; includes sample clamping + field inference logic. |
| CosmosDBShell.Tests/CommandTests/SchemaCommandTests.cs | Adds unit tests for command registration and helper behaviors (clamping + inference). |
| CHANGELOG.md | Records the new schema command/tool as a new feature. |
Comment on lines
+611
to
+613
| field types inferred from the sample. It is read-only and issues a single bounded query, | ||
| making it a cheap way for agents and users to discover a container's structure without | ||
| re-sampling or guessing field names. |
Comment on lines
+653
to
+654
| "indexingMode": "consistent", | ||
| "automatic": true, |
Comment on lines
+64
to
+67
| var settings = await CosmosResourceFacade.GetContainerSettingsAsync(connectedState, databaseName!, containerName!, token); | ||
| var sampledDocuments = await SampleDocumentsAsync(container, sampleSize, token); | ||
| long? documentCountEstimate = await ReadDocumentCountEstimateAsync(container, token); | ||
| var fields = InferSchema(sampledDocuments); |
Comment on lines
+91
to
+95
| /// <summary> | ||
| /// Infers a per-field type summary from a bounded set of sampled documents. Fields are | ||
| /// reported using dot notation for nested objects up to <paramref name="maxDepth"/> levels. | ||
| /// Each field lists the distinct JSON types observed and the number of sampled documents in | ||
| /// which the field was present. |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Suppressed comments (1)
docs/commands.md:654
- The sample output shows
"indexingMode": "consistent", but the implementation surfacesContainerIndexingPolicyView.IndexingMode, which is populated viaindexingPolicy.IndexingMode.ToString()and will be Pascal-cased (e.g.,"Consistent", same as the existinginfocommand output). This makes the sample output misleading.
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
Comment on lines
+10
to
+14
| using System.Text.Json; | ||
| using Azure.Data.Cosmos.Shell.Mcp; | ||
| using Azure.Data.Cosmos.Shell.Parser; | ||
| using Azure.Data.Cosmos.Shell.Util; | ||
| using global::Azure.Data.Cosmos.Shell.Core; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the M4 schema / describe discovery tool from the Agentic & Automation Roadmap.
Adds a read-only
schemacommand (and matching read-only MCP tool) that returns a cheap, bounded discovery summary of a Cosmos DB container so agents and users can understand a container's structure without repeatedly re-sampling or guessing field names.For the current container (or
--database/--container),schemareturns:x-ms-resource-usagequota header, no scanstring,number,boolean,object,array,null), and how many sampled documents contained each field--sample <n>selects how many documents to sample and is clamped to1-100(default20) so the single discovery query always stays bounded and read-only.Sample output
{ "database": "MyDB", "container": "Products", "partitionKeyPaths": ["/category"], "documentCountEstimate": 1280, "sampleSize": 20, "sampledDocuments": 20, "indexingPolicy": { "indexingMode": "consistent", "automatic": true, "includedPaths": 1, "excludedPaths": 1, "compositeIndexes": 0, "spatialIndexes": 0, "vectorIndexes": 0 }, "fields": [ { "path": "id", "types": ["string"], "presence": 20 }, { "path": "category", "types": ["string"], "presence": 20 }, { "path": "price", "types": ["number"], "presence": 18 } ] }Acceptance criteria
[CosmosCommand("schema")]with[McpAnnotation(ReadOnly = true, Idempotent = true, OpenWorld = true)], auto-exposed as a read-only toolSELECT * FROM ccapped atMaxItemCount, sample size clamped to 1-100; document count comes from the quota header (no scan)docs/commands.md, CHANGELOG, and unit tests for the sample-clamping and type-inference helpersTesting
dotnet build CosmosDBShell/CosmosDBShell.csproj— 0 warnings, 0 errorsdotnet build CosmosDBShell.Tests/CosmosDBShell.Tests.csprojdotnet test— 630 passed, 15 skipped (integration tests requiring a live account), 0 failed, including 12 newSchemaCommandTestsFixes #160