Foundgine MCP Server

<picture> <source media="(prefers-color-scheme: dark)" src="docs-site/assets/logo/foundgine-logo.svg"> <img src="docs-site/assets/logo/foundgine-logo.svg" alt="Foundgine" width="360"> </picture>

Foundgine

Foundgine gives AI agents and other callers a way to express what they want, while your application retains full control over how anything is executed. It introduces a single, application‑controlled semantic execution boundary that sits between:

• caller intent,
• your domain meaning,
• your authorization rules,
• and the actual operations performed on your data, APIs, GraphQL, MCP tools, or backend systems.

This boundary ensures that agents can propose actions, but only your application decides what is allowed, what is safe, and what is actually executed.

Go to website →

Where to read next

I want to...	Go to
Run something now	Get started
Understand the idea and the boundary	docs/WHY-FOUNDGINE.md · docs/ARCHITECTURE.md
Browse every feature in plain language	Feature and capability wiki
Pick a database, ORM (EF Core / JPA) or search provider	Provider catalogue · ORM providers
Add GraphQL, Keycloak or Temporal	Extensions
Check implementation and test coverage	Source coverage · Conformance and hardening

The problem

As applications expose more functionality to callers, you can end up with lots of individual tools/endpoints, each containing its own validation, authorization, query logic, and business rules.

Foundgine centralizes that responsibility into a semantic execution boundary. The caller expresses intent, while the application remains responsible for deciding what that intent means, what is allowed, and how it gets executed.

A complex application may have several ways to express an operation:

Application code
GraphQL
JSON
AI-generated intent

Without a common semantic execution layer, each surface tends to grow its own rules for:

• what entities and fields exist;
• which relationships can be traversed;
• which filters are valid;
• what the caller is authorized to access; and
• how the request becomes database or service operations.

That produces duplicated semantics and inconsistent security boundaries.

The idea

Retrieval can discover candidates and evidence, but retrieval is not authorization. The application owns identity and policy; providers execute the already-authorized artifact. Foundgine centralizes this responsibility.

Get started

The fastest path is the Supply Chain sample pair:

• Starter: the smallest realistic application boundary.

  • .NET — src/csharp/samples/Foundgine.SupplyChain: Build it step by step · Understand why it is structured this way
  • Java — src/java/samples/foundgine-supply-chain: Build it step by step · Understand why it is structured this way

• Advanced: richer semantics, grounding, retrieval, authorization and adversarial testing.

  • .NET — src/csharp/samples/Foundgine.SupplyChain.Advanced: start at docs/00-Overview-And-Setup.md and follow 01–05.
  • Java — src/java/samples/foundgine-supply-chain-advanced: SupplyChain-Advanced-Tutorial.md.

• Enterprise integration example (separate work-in-progress repository):

  • .NET/Java CRM, ERP, Temporal and Keycloak example — Foundgine-e2e-example: Tutorial. Check that repository's README for its current build and verification status; it is not a certified Foundgine sample.

For the conceptual path, use docs/README.md or the documentation site.

A concrete example

Two callers can ask for the same thing in different words:

• Canonical: “show me overdue purchase orders from our top supplier in Texas”
• Paraphrase: “show me the overdue buys from our top seller in Texas”

Foundgine does not treat the paraphrase as a fuzzy guess at a different operation. In the Supply Chain semantic contract, Buy/Buys are declared aliases of PurchaseOrder, and Seller is a declared alias of Supplier. Both sentences are grounded onto the same canonical semantic identities before authorization or planning ever runs — the diagram below follows one request all the way from words to a database call.

Tests:

• .NET — SupplyChainGroundingAliasTests.cs (advanced Supply Chain sample) · SemanticAliasSynonymGroundingTests.cs (core semantics).
• Java — SupplyChainGroundingAliasParityTest.java (advanced Supply Chain sample) · SemanticAliasSynonymGroundingParityTest.java (core semantics).

<p align="center"><img src="docs/assets/overdue-purchase-orders-alias-flow.svg" alt="Foundgine alias-matched Supply Chain request from caller intent through semantic resolution, authorization, planning, PostgreSQL execution and evidence." width="100%"></p>

The request, layer by layer

#	Layer	What happens
1	Caller intent	The caller sends either sentence. Neither one contains SQL or provider instructions.
2	Intent representation	The request becomes structured intent — the caller never constructs a physical query directly.
3	Semantic Model	The generated contract exposes canonical meanings and their declared aliases: PurchaseOrder ← Buy, Buys and Supplier ← Vendor, Seller.
4	Semantic Operation Graph	The request becomes application meaning: overdue purchase-order semantics, a ranked “top supplier” relationship, and a Texas constraint.
5	Retrieval	Relational, fuzzy/full-text, BM25/search, or graph strategies propose candidates and evidence. They never grant authority.
6	Semantic Resolution	buys → PurchaseOrder and seller → Supplier. The aliases normalize to the same canonical identities as the original wording.
7	Authorization	Application policy runs against the resolved semantic graph and caller identity. Retrieval results cannot bypass this step.
8	Plan Binding	The authorized decision is bound to a provider-independent execution plan.
9	ExecutionIR	The executable artifact carries the resolved plan and its authorization provenance across the execution boundary.
10	Provider	Only now does a physical provider — PostgreSQL, here — receive the already-authorized artifact.
11	Execution	The provider executes the constrained plan; it does not reinterpret caller vocabulary.
12	Evidence	The result carries evidence of what was resolved and executed. Evidence records what happened — it does not grant authority.

The invariant: alias matching changes vocabulary, not authority. “Buys” does not create a new capability, and “seller” does not create a second supplier meaning — both are application-declared paths to identities that already exist.

When more than one meaning is legal

Aliases collapse different words onto one meaning. Sometimes the ambiguity runs the other way: the same word is a legal match for two different meanings at once, and neither the graph nor a retrieval score can tell them apart on its own.

Take the request “active customers”. Both of the following are structurally valid readings:

• a customer whose account is enabled (Customer.AccountEnabled)
• a customer who placed a recent order (Customer.HasRecentOrder)

A fuzzy/BM25/vector retriever can legitimately return both, with close scores (0.91 vs. 0.89). Foundgine does not break the tie by picking whichever scored higher: a higher retrieval score is not evidence of what the caller meant, and authorization can’t rescue a wrong guess — a request built from the wrong meaning is still a fully authorized request. It would just be a perfectly authorized misunderstanding.

<p align="center"><img src="docs/assets/lexical-grounding-clarification-flow.svg" alt="Foundgine lexical grounding when two meanings are legal: fuzzy retrieval returns tied candidates, both form a valid semantic path, grounding reports RequiresClarification, and the caller picks one before authorization runs." width="100%"></p>

What Foundgine does instead of guessing

Stage	What happens
Retrieval (fuzzy)	Every plausible reading comes back as a candidate, each with its own score and evidence. Retrieval only ever proposes — it never decides.
Graph-constrained resolution	Each candidate is checked against the frozen semantic contract. Both AccountEnabled and HasRecentOrder form a legal path. A legal path only proves an interpretation is possible — not that it is the one intended.
Grounding decision	SemanticLexicalResolver.Ground compares the two paths’ signatures — what each one means, not how it got there. The signatures differ and neither dominates on confidence, so the outcome is GroundingOutcome.RequiresClarification: Committed stays null, and both readings are listed in CompetingInterpretations, each with its own steps, confidence, and evidence.
Caller chooses	The competing meanings are surfaced back as a clarifying question — “Did you mean customers with an enabled account, or customers with a recent order?” — instead of silently executing a guess.
Same boundary as everyone else	Once the caller picks one, that single interpretation goes through the exact same Authorization → Planning → Execution path as any other request.

The invariant: a legal semantic path is not proof of intent. When retrieval genuinely can’t tell two meanings apart, Foundgine surfaces the ambiguity instead of silently authorizing a coin flip.

The same mechanism fails closed the same way in two other cases: when a resource limit (token count, search budget, timeout) stops the search before it can prove there is only one meaning (GroundingOutcome.BudgetExceeded), and when no legal interpretation exists at all (GroundingOutcome.Unresolved). Neither one ever falls back to a best-effort guess.

Read more: Lexical grounding covers fuzzy retrieval, the resolver’s complexity bounds, and worked adversarial examples end-to-end. Grounding decisions covers the full GroundingDecision shape, the difference between “different evidence for the same meaning” and “different meanings,” and the complete active customers walkthrough, backed by a passing test.

Why the boundary matters

The number of independent execution surfaces is a security and maintenance multiplier. A tool-per-capability design can give an agent dozens of places where authorization, tenant filtering and query construction are implemented differently. Foundgine centralizes the semantic decision without making a transport or database the center of the architecture.

For the deeper rationale, read:

• docs/WHY-FOUNDGINE.md
• docs/APPLICATION-CATEGORIES.md
• docs/ARCHITECTURE.md
• docs/AUTHORIZATION.md
• docs/SECURITY.md
• docs/AI-AGENT.md

Package shape

The core package family has four architectural packages (the .NET names are shown; Java uses foundgine-* artifacts under io.github.cristianbarragan). Optional integrations and tooling are packaged separately:

Package	Responsibility
Foundgine.Core	Semantic model, metadata, intent, planning and provider-independent contracts
Foundgine.Runtime	Application-facing orchestration, authorization and execution
Foundgine.Providers	Concrete storage (SQL, EF Core, JPA, in-memory, search), events, gateway, AI/model, MCP and AOT
Foundgine.Extensions	Optional GraphQL, Keycloak identity and Temporal workflow integrations
Foundgine.Providers.AgentFramework	Optional .NET Microsoft Agent Framework adapter; packable source project, not yet build-verified or released

The normal application starting point is Foundgine.Runtime + Foundgine.Providers. The Java Maven reactor contains the implemented foundgine-migrations module and optional Spring Boot and LangChain4j integrations. The latter have source and test definitions, but their dependency pins and runtime verification remain unverified in this snapshot. The Central publishing configuration includes these modules and excludes the build-time foundgine-aot-generator. See the package guide for the current boundary map.

Providers and extensions at a glance

A provider does the real work against infrastructure; an extension connects an outside framework or service. Both sit outside the semantic boundary: they never decide what is allowed.

Need	Use	Notes
Relational database, Foundgine writes the SQL	SQL provider (incl. PostgreSQL batched mutations)	.NET and Java
Your existing ORM	EF Core (.NET) or JPA (Java) over a shared ORM-neutral core	Permission filters are always added; maturity is tracked per capability. See ORM providers
Tests and demos, no database	In-memory provider	Deliberately limited
Understanding free-form wording	Elasticsearch, PostgreSQL + pgvector, PostgreSQL trigram/full-text retrieval	Candidates and evidence only, never authority
Durable events and reliable delivery	Event store and outbox	At-least-once delivery
One front door for other products	Gateway (approvals, events, status, diagnostics)	Opaque one-time approval handles
AI agents and tools	MCP tools, Microsoft.Extensions.AI models and the optional Microsoft Agent Framework adapter (source present, unverified)	Model supplies intent, host supplies authority
GraphQL API	GraphQL extension (Hot Chocolate for .NET; GraphQL Java for Java)	Translates only
Keycloak logins	Keycloak extension	Short-lived signed warrants
Long-running processes	Temporal extension	Retries, timers, approvals, compensation

The full inventory with source paths is the Provider catalogue and the Extensions page. Receipts, audit and diagnostics are explained in Insights, evidence and auditing.

Evidence

The repository contains controlled benchmarks and deterministic security tests. The public evidence distinguishes measured tool calls, latency, RPS and success/failure counts from estimated context metrics.

• Agent benchmark explorer
• Supply Chain E2E
• Security PenTest
• src/csharp/benchmarks/AgentEndToEnd/README.md

Benchmark results are workload-specific and should not be generalized beyond the published experiment.

Historical red-team run (7 September 2026)

A recorded manual run of Foundgine.RedTeam against the Advanced Supply Chain .NET sample sent 18 attack attempts — cross-tenant probes, role/identity claim spoofing, claim-scope widening, write/capability escalation, and unauthenticated-actor calls — across the semantic authorization API and execution/tool-calling API. Every adversarial attempt was denied or blocked; only the two intentionally legitimate baseline calls succeeded. This is evidence for that sample run, not a current release certification or proof of Java parity. See docs/SECURITY.md for the run details. The current CI opt-in gaps are documented in docs/POSTGRES-E2E.md and the Supply Chain PenTest fixture README.

Development

# .NET 10
cd src/csharp
dotnet restore Foundgine.sln
dotnet build Foundgine.sln
dotnet test Foundgine.sln

# Java 27
cd ../java
mvn -U clean verify -Dgpg.skip=true

PostgreSQL integration testing: docs/POSTGRES-E2E.md. Shared cross-language test vectors and scenarios: src/conformance/README.md. See docs/TESTING.md for solution exclusions and test commands. The repository workflows under .github/workflows/ define the automated build and release gates; a workflow definition is not proof that a particular run passed or that an opt-in test actually executed.

Documentation

• Documentation index — the reading path.
• Feature and capability wiki — by capability, in plain language: providers (EF Core, JPA, SQL, search), extensions, gateway, MCP, AOT, auditing and operations.
• Website · CHANGELOG.md

Release 3.3.5

Current server release: 3.3.5 · .NET 10 and Java 27; client SDK publication and verification status is tracked separately

Foundgine 3.3.5 advances the Supply Chain persistence path across the .NET and Java samples and adds Java model-derived PostgreSQL migrations. The Java fluent persistence metadata now carries defaults, identity generation, named/composite foreign keys and referential actions, CHECK constraints, index access methods/operator classes, and required PostgreSQL extensions into the migration schema, differ and SQL generator. The starter and Advanced samples now include physical-schema projections, migration snapshots/history, rollback generation and schema-parity tests.

The release also includes the Java fluent-model/JPA integration updates and the .NET Supply Chain starter's typed semantic query and persistence/sample improvements. Version metadata is aligned across .NET, Java/Maven, MCP manifests, TypeScript, Python and Rust/WASM client metadata. The transport SDKs remain transport clients; they do not claim the C#/Java semantic runtime or persistence-provider surface.

License

Foundgine is licensed under the Apache License 2.0.