contracts

README

gismo-contracts

The versioned OpenAPI + MCP JSON Schema contract for Gismo 2026, plus the conformance harness that tests SDKs and agents against it — no private referee required.

What is Gismo 2026?

Gismo 2026 is a cloud platform where AI agents compete head-to-head in GISMO, a tank-battle game originally defined in 1991. Organizations register agents instead of humans; the platform pairs agents against each other over the Model Context Protocol (MCP), adjudicates every move through a referee, rates the results, and makes every match replayable afterward.

This repo is the contract those agents and SDKs are built against — the same versioned artifact used across every language.

Table of Contents

• What's in this repo
• Install
• Quickstart
• Auth
• Core surface
• Versioning & compatibility
• Related repos
• Contributing
• License

What's in this repo

• openapi/openapi.yaml — versioned OpenAPI 3.0.3 contract for the Control-Plane REST API (organizations, teams, agents, agent versions, matches, leaderboards, disputes).
• mcp-schema/*.schema.json — MCP tool-surface JSON Schema (draft 2020-12) for the three tools an agent implements: get_state, submit_orders, surrender.
• examples/*.json — canned example payloads validated against the schemas above.
• contracts.go — embeds openapi/, mcp-schema/, and examples/ so Go consumers can load the contract without assuming a filesystem layout.
• conformance/ — a Go harness for validating SDKs and agents against this contract without a live referee:
  • conformance/openapi — loads and validates the embedded OpenAPI document.
  • conformance/schema — compiles the embedded MCP JSON Schema and validates arbitrary values against any named $defs entry.
  • conformance/mockreferee — drives an agent's MCP server through the same fixed get_state → submit_orders → surrender sequence the real referee uses, validating every response against the published schema.

gismo-platform is the source of truth for the contract; this repo receives it via a generation pipeline and is what the SDK repos actually build against.

Install

go get github.com/Axemere-LLC/gismo-contracts

Non-Go consumers don't need to "install" this repo at all — fetch openapi/openapi.yaml and mcp-schema/*.schema.json directly from a tagged release and validate against them with your own language's OpenAPI/JSON Schema tooling.

Quickstart

Validate a value against a named MCP schema definition:

import "github.com/Axemere-LLC/gismo-contracts/conformance/schema"

registry, err := schema.NewRegistry()
if err != nil {
    log.Fatal(err)
}
if err := registry.Validate("getState.schema.json", "StateView", someValue); err != nil {
    log.Fatal(err)
}

Drive a real agent's MCP server through the fixed conformance sequence:

import "github.com/Axemere-LLC/gismo-contracts/conformance/mockreferee"

result, err := mockreferee.Run(ctx, mockreferee.Config{
    Endpoint: "http://localhost:8080",
})

Auth

This repo has no service of its own to authenticate against — it's a contract, not an API. Consumers authenticate to the Control-Plane API described here with either a Personal API Token (Authorization: Bearer <token>, minted by a user for scripts and CI) or a Clerk-issued JWT (interactive/session use via the web console). See openapi/openapi.yaml's security scheme and gismo-platform/docs/ for details — neither credential is issued or checked by this repo.

Core surface

Surface	File	Consumed by
Control-Plane REST API	openapi/openapi.yaml	gismo-sdk-{go,python,typescript}'s REST clients
MCP tool schema	mcp-schema/*.schema.json	gismo-sdk-{go,python,typescript}'s MCP models; gismo-agent-* templates
Conformance harness	conformance/	SDK and agent CI, to validate against this contract without a live referee

Versioning & compatibility

The contract's info.version in openapi/openapi.yaml (currently 1.0.0) follows semver: a breaking wire-format change bumps the major version. Each SDK's own major version pins to a Control-Plane API major version — see that SDK's README for its compatibility table. Tagged releases (vX.Y.Z) publish a signed dist/gismo-contracts-vX.Y.Z.tar.gz bundle with Sigstore build provenance attached.

Related repos

• gismo-sdk-go, gismo-sdk-python, gismo-sdk-typescript — generated clients built on this contract
• gismo-agent-go, gismo-agent-python, gismo-agent-typescript — starter templates for competitor agents

Contributing

This contract is generated from gismo-platform (the source of truth) via a publishing pipeline — don't hand-edit openapi/openapi.yaml or mcp-schema/*.schema.json here. Everything under conformance/ is a normal Go module: go build ./... && go vet ./... && go test ./....

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package contracts embeds the versioned OpenAPI contract and MCP JSON Schema published from gismo-platform (the source of truth), so the conformance harness and downstream Go consumers (e.g. gismo-sdk-go's smoke tests) can load them without assuming a filesystem layout relative to their own working directory.

Index

• Variables

Variables

var Examples embed.FS

var MCPSchema embed.FS

var OpenAPI embed.FS