Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -150,15 +150,17 @@ java:
# within a week.
api:
@go run ./internal/apisurface/generate .
@go run ./internal/apisurface/outputschema . > /dev/null
@echo "api surface written"

# api-check fails if the generated files are out of date, so a tool added
# without regenerating them is caught in CI rather than read as truth later.
api-check:
@go run ./internal/apisurface/generate .
@git diff --quiet -- docs/API.md docs/api/surface.json || { \
echo "docs/API.md or docs/api/surface.json is stale — run 'make api' and commit the result"; \
git --no-pager diff --stat -- docs/API.md docs/api/surface.json; \
@go run ./internal/apisurface/outputschema . > /dev/null
@git diff --quiet -- docs/API.md docs/api/surface.json internal/agent/outputschema_gen.go || { \
echo "docs/API.md, docs/api/surface.json or internal/agent/outputschema_gen.go is stale — run 'make api' and commit the result"; \
git --no-pager diff --stat -- docs/API.md docs/api/surface.json internal/agent/outputschema_gen.go; \
exit 1; }
@echo "api surface current"

Expand Down
14 changes: 12 additions & 2 deletions docs/guides/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,8 +152,18 @@ cut short and its schema reduced to the argument names:

Every schema says `additionalProperties: false`, so an argument a tool does
not take is refused rather than ignored. `readOnlyHint` is on every tool:
true for the 19 that only read — `app_map`, `app_text`, `app_state` and the
like — and false for everything that can change the device.
true for the 22 that only read — `app_map`, `app_text`, `app_state` and the
like — and false for everything that can change the device; tools that act
also say `destructiveHint` and `idempotentHint` where they can (section 7).

68 of the 78 tools also carry an `outputSchema`: the shape of the
`structuredContent` every successful call returns, so a client can check
what it is handed. It is generated from the code by Go's type checker
(`internal/apisurface/outputschema`, run by `make api`), and only for a
tool that always answers with one type; the other ten, such as
`app_screenshot`, `app_batch` and `app_logs`, answer with an image or with
one of several shapes, and carry none. A test holds every schema to empty
and filled values of its type, and `make ci` fails when one is out of date.

## 4. Answers: text, data and images

Expand Down
17 changes: 17 additions & 0 deletions internal/agent/outputschema.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
package agent

import "encoding/json"

// OutputSchema is the tool's MCP outputSchema, or nil for a tool without
// one (outputschema_gen.go says which have one; make api regenerates it).
func OutputSchema(name string) map[string]interface{} {
raw, ok := outputSchemas[name]
if !ok {
return nil
}
var s map[string]interface{}
if json.Unmarshal([]byte(raw), &s) != nil {
return nil
}
return s
}
153 changes: 153 additions & 0 deletions internal/agent/outputschema_gen.go

Large diffs are not rendered by default.

204 changes: 204 additions & 0 deletions internal/agent/outputschema_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
package agent

import (
"encoding/json"
"fmt"
"reflect"
"sort"
"testing"
"time"
)

// Every tool's outputSchema holds the values its type takes, as
// encoding/json writes them: empty, with every slice and pointer nil, and
// filled, with every field set and every slice and map holding one element.
// A client may refuse a result that does not match its tool's schema, so a
// schema that is wrong is worse than none.
func TestEveryOutputSchemaHoldsItsTypesValues(t *testing.T) {
if len(outputZeros) != len(outputSchemas) {
t.Fatalf("%d schemas and %d types: regenerate with make api", len(outputSchemas), len(outputZeros))
}
names := make([]string, 0, len(outputZeros))
for n := range outputZeros {
names = append(names, n)
}
sort.Strings(names)
for _, name := range names {
schema := OutputSchema(name)
if schema == nil || schema["type"] != "object" {
t.Errorf("%s: schema %v is no object", name, schema)
continue
}
zero := outputZeros[name]()
for which, v := range map[string]interface{}{"empty": zero, "filled": filled(reflect.TypeOf(zero), 0).Interface()} {
raw, err := json.Marshal(v)
if err != nil {
t.Errorf("%s %s: %v", name, which, err)
continue
}
var doc interface{}
if err := json.Unmarshal(raw, &doc); err != nil {
t.Fatal(err)
}
if err := validate(schema, doc, "$"); err != nil {
t.Errorf("%s, %s: %v\n%s", name, which, err, raw)
}
}
}
}

// The validator is held to a value it must refuse, so its passes mean
// something: a required field missing, and a string where a number goes.
func TestTheValidatorRefuses(t *testing.T) {
s := map[string]interface{}{"type": "object", "required": []interface{}{"n"},
"properties": map[string]interface{}{"n": map[string]interface{}{"type": "integer"}}}
if validate(s, map[string]interface{}{}, "$") == nil {
t.Error("a missing required field passed")
}
if validate(s, map[string]interface{}{"n": "1"}, "$") == nil {
t.Error("a string passed as an integer")
}
if validate(s, map[string]interface{}{"n": 1.0}, "$") != nil {
t.Error("an integer was refused")
}
}

func TestTheToolsListCarriesTheSchemas(t *testing.T) {
with := 0
for _, tl := range GetToolSchemas() {
if tl.OutputSchema != nil {
with++
}
}
if with != len(outputSchemas) || with < 60 {
t.Errorf("%d tools list an outputSchema, %d generated", with, len(outputSchemas))
}
}

// filled is a value of t with every field set.
func filled(t reflect.Type, depth int) reflect.Value {
v := reflect.New(t).Elem()
if depth > 6 {
return v
}
if t == reflect.TypeOf(time.Time{}) {
return reflect.ValueOf(time.Unix(1, 0).UTC())
}
switch t.Kind() {
case reflect.String:
v.SetString("x")
case reflect.Bool:
v.SetBool(true)
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
v.SetInt(1)
case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
v.SetUint(1)
case reflect.Float32, reflect.Float64:
v.SetFloat(1.5)
case reflect.Pointer:
v.Set(filled(t.Elem(), depth+1).Addr())
case reflect.Slice:
s := reflect.MakeSlice(t, 1, 1)
s.Index(0).Set(filled(t.Elem(), depth+1))
v.Set(s)
case reflect.Map:
m := reflect.MakeMap(t)
if t.Key().Kind() == reflect.String {
m.SetMapIndex(reflect.ValueOf("k").Convert(t.Key()), filled(t.Elem(), depth+1))
}
v.Set(m)
case reflect.Struct:
for i := 0; i < t.NumField(); i++ {
if f := t.Field(i); f.IsExported() {
v.Field(i).Set(filled(f.Type, depth+1))
}
}
case reflect.Interface:
if t.NumMethod() == 0 {
v.Set(reflect.ValueOf("x"))
}
}
return v
}

// validate holds doc to the part of JSON Schema the generator writes.
func validate(schema map[string]interface{}, doc interface{}, at string) error {
if len(schema) == 0 {
return nil
}
types := []string{}
switch t := schema["type"].(type) {
case string:
types = append(types, t)
case []interface{}:
for _, x := range t {
types = append(types, x.(string))
}
}
ok := len(types) == 0
for _, ty := range types {
if fits(ty, doc) {
ok = true
}
}
if !ok {
return fmt.Errorf("%s: %T %v is not %v", at, doc, doc, types)
}
switch d := doc.(type) {
case map[string]interface{}:
props, _ := schema["properties"].(map[string]interface{})
if req, ok := schema["required"].([]interface{}); ok {
for _, r := range req {
if _, has := d[r.(string)]; !has {
return fmt.Errorf("%s: required %q missing", at, r)
}
}
}
for k, v := range d {
if ps, ok := props[k].(map[string]interface{}); ok {
if err := validate(ps, v, at+"."+k); err != nil {
return err
}
} else if ap, ok := schema["additionalProperties"].(map[string]interface{}); ok {
if err := validate(ap, v, at+"."+k); err != nil {
return err
}
}
}
case []interface{}:
if items, ok := schema["items"].(map[string]interface{}); ok {
for i, v := range d {
if err := validate(items, v, fmt.Sprintf("%s[%d]", at, i)); err != nil {
return err
}
}
}
}
return nil
}

func fits(ty string, doc interface{}) bool {
switch ty {
case "null":
return doc == nil
case "object":
_, ok := doc.(map[string]interface{})
return ok
case "array":
_, ok := doc.([]interface{})
return ok
case "string":
_, ok := doc.(string)
return ok
case "boolean":
_, ok := doc.(bool)
return ok
case "number":
_, ok := doc.(float64)
return ok
case "integer":
f, ok := doc.(float64)
return ok && f == float64(int64(f))
}
return false
}
4 changes: 4 additions & 0 deletions internal/agent/protocol.go
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,10 @@ type Tool struct {
// Annotations are MCP's hints about the tool; readOnlyHint is set on
// every tool, from readonly.go.
Annotations map[string]interface{} `json:"annotations,omitempty"`
// OutputSchema is the shape of the structuredContent every successful
// call returns, generated from the code (outputschema_gen.go), and
// absent for a tool that does not always return one shape.
OutputSchema map[string]interface{} `json:"outputSchema,omitempty"`
}

type ToolsCallParams struct {
Expand Down
1 change: 1 addition & 0 deletions internal/agent/schema.go
Original file line number Diff line number Diff line change
Expand Up @@ -2325,6 +2325,7 @@ func GetToolSchemas() []Tool {
}
for i := range tools {
tools[i].Annotations = Annotations(tools[i].Name)
tools[i].OutputSchema = OutputSchema(tools[i].Name)
}
return tools
}
Expand Down
Loading
Loading