Feature/configurable business tools - #151
Open
Theo van Kraay (TheovanKraay) wants to merge 11 commits into
Open
Conversation
added 11 commits
August 5, 2026 16:59
…and fail-closed validator
…rojection, authorization, and operation execution pipeline
…g, injection, projection, authorization, batch)
… for banking-style containers
…validation and emulator integration tests - Add samples/banking/cosmos-tools.yaml covering point-read, query, vector-search, create, and transactional-batch - Document bank_transfer partition analysis (cross-account transfer cannot be a single batch) - Add FlexibleStringConverter so numeric YAML literals bind to template string fields - Add end-to-end emulator integration tests (skipped when emulator absent)
…lity matrix, and banking migration walkthrough
…ample to demonstrate the runtime is domain-agnostic - Add samples/README.md and samples/ecommerce/cosmos-tools.yaml (point-read, query, hybrid-search, patch allow-list, bounded sequence) - Prove genericness with EcommerceSampleConfigTests loading on the identical engine - Cross-link from declarative-tools docs and CHANGELOG
Add a runtime LogWarning (opt-in path only), EXPERIMENTAL code comments/XML docs on the entry points, and experimental notices in README, docs/declarative-tools, and CHANGELOG. Additive only; no behavior change.
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
1 participant
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.
Why
Today the toolkit exposes a small set of low-level, mostly read-only primitives (
list_databases,find_document_by_id,vector_search, and so on). They are great for exploration and IDE/agent "talk to my data" scenarios, but they are the wrong abstraction for production agentic applications. You don't want to hand an agent raw database verbs and hope it composes them safely. Real apps need business-facing tools such asget_account_balance,create_service_request, andbank_transfer, with validation, authorization, tenant isolation, and governance baked in. There is currently no way to define those without writing bespoke MCP handler code.What this adds
An additive, opt-in declarative layer. You define business tools in a YAML (or JSON) file and the toolkit registers them as first-class MCP tools alongside the existing built-ins.
sequencecomposition (with assertions, generated ids, and system timestamps).ICosmosGateway; hierarchical (sub-partitioned) partition keys are supported.Compatibility
Fully backward compatible. The runtime is dormant unless
COSMOS_TOOLS_CONFIG(orCosmosMcp:ToolsConfigPath) is set, so no existing tool, schema, default, or environment variable changes. A GA-compatibility matrix and docs are included underdocs/declarative-tools/.Testing
45 new unit tests plus emulator integration tests (63 of 68 pass; the 5 failures are pre-existing baseline issues and are documented). I also validated the runtime end-to-end against a real banking scenario: running this toolkit as a sibling MCP server against real Azure Cosmos DB and Azure OpenAI, with a LangGraph agent invoking
bank_balanceandbank_transferon it. That banking sample integration is a separate, follow-up change and is not required by this PR. This change is self-contained and can merge on its own.Follow-up (not a dependency)
A companion change to the banking multi-agent sample will wire the app to consume this toolkit as a sibling server (Cosmos tools on the toolkit, non-Cosmos tools on the banking server). It depends on this PR, not the other way around, and will be raised separately.