|
| 1 | +// Tests for the read tools' optional inputs (#3953), driven through an SDK |
| 2 | +// Client over an in-memory transport: read_graph's entityTypes filter, the |
| 3 | +// observationLimit every read tool takes (with the observationCount it adds), |
| 4 | +// and search_nodes' limit. Each option is optional, so the default results |
| 5 | +// are pinned too: a call without them returns what it always has, and the |
| 6 | +// knowledge-graph resource never carries observationCount. |
| 7 | +import { describe, it, expect, beforeEach, afterEach } from "vitest"; |
| 8 | +import type { Client } from "@modelcontextprotocol/client"; |
| 9 | +import { call, connect, makeTempGraph, textOf } from "./helpers.js"; |
| 10 | +import type { Connection } from "./helpers.js"; |
| 11 | + |
| 12 | +const alice = { |
| 13 | + name: "Alice", |
| 14 | + entityType: "person", |
| 15 | + observations: ["works at Acme Corp", "likes tea", "plays chess"], |
| 16 | +}; |
| 17 | +const bob = { |
| 18 | + name: "Bob", |
| 19 | + entityType: "person", |
| 20 | + observations: ["likes programming"], |
| 21 | +}; |
| 22 | +const acme = { |
| 23 | + name: "Acme Corp", |
| 24 | + entityType: "organization", |
| 25 | + observations: ["makes anvils", "founded in 1900"], |
| 26 | +}; |
| 27 | +const empty = { name: "Nobody", entityType: "placeholder", observations: [] }; |
| 28 | +const aliceKnowsBob = { from: "Alice", to: "Bob", relationType: "knows" }; |
| 29 | +const aliceWorksAtAcme = { |
| 30 | + from: "Alice", |
| 31 | + to: "Acme Corp", |
| 32 | + relationType: "works_at", |
| 33 | +}; |
| 34 | +const bobKnowsAlice = { from: "Bob", to: "Alice", relationType: "knows" }; |
| 35 | + |
| 36 | +describe("read tool options (#3953)", () => { |
| 37 | + let conn: Connection; |
| 38 | + let client: Client; |
| 39 | + let cleanup: () => Promise<void>; |
| 40 | + |
| 41 | + beforeEach(async () => { |
| 42 | + const graph = await makeTempGraph(); |
| 43 | + cleanup = graph.cleanup; |
| 44 | + conn = await connect(graph.filePath); |
| 45 | + client = conn.client; |
| 46 | + await call(client, "create_entities", { |
| 47 | + entities: [alice, bob, acme, empty], |
| 48 | + }); |
| 49 | + await call(client, "create_relations", { |
| 50 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 51 | + }); |
| 52 | + }); |
| 53 | + |
| 54 | + afterEach(async () => { |
| 55 | + await conn.close(); |
| 56 | + await cleanup(); |
| 57 | + }); |
| 58 | + |
| 59 | + // Call a tool and return its structured result, checking that the text |
| 60 | + // block carries the same graph. |
| 61 | + async function read(name: string, args: Record<string, unknown>) { |
| 62 | + const result = await call(client, name, args); |
| 63 | + expect(result.isError).toBeFalsy(); |
| 64 | + expect(textOf(result)).toBe( |
| 65 | + JSON.stringify(result.structuredContent, null, 2), |
| 66 | + ); |
| 67 | + return result.structuredContent; |
| 68 | + } |
| 69 | + |
| 70 | + // The text of a call that must fail input validation. |
| 71 | + async function rejected(name: string, args: Record<string, unknown>) { |
| 72 | + const result = await call(client, name, args); |
| 73 | + expect(result.isError).toBe(true); |
| 74 | + return textOf(result); |
| 75 | + } |
| 76 | + |
| 77 | + describe("defaults", () => { |
| 78 | + it("read_graph without options returns every observation and no counts", async () => { |
| 79 | + expect(await read("read_graph", {})).toEqual({ |
| 80 | + entities: [alice, bob, acme, empty], |
| 81 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 82 | + }); |
| 83 | + }); |
| 84 | + |
| 85 | + it("search_nodes and open_nodes without options return full entities", async () => { |
| 86 | + expect(await read("search_nodes", { query: "acme" })).toEqual({ |
| 87 | + entities: [alice, acme], |
| 88 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 89 | + }); |
| 90 | + expect(await read("open_nodes", { names: ["Bob"] })).toEqual({ |
| 91 | + entities: [bob], |
| 92 | + relations: [aliceKnowsBob, bobKnowsAlice], |
| 93 | + }); |
| 94 | + }); |
| 95 | + |
| 96 | + it("the knowledge-graph resource is unaffected", async () => { |
| 97 | + const { contents } = await client.readResource({ |
| 98 | + uri: "memory://knowledge-graph", |
| 99 | + }); |
| 100 | + const [content] = contents; |
| 101 | + expect("text" in content && JSON.parse(content.text)).toEqual({ |
| 102 | + entities: [alice, bob, acme, empty], |
| 103 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 104 | + }); |
| 105 | + }); |
| 106 | + }); |
| 107 | + |
| 108 | + describe("observationLimit", () => { |
| 109 | + it("0 gives read_graph an overview of names, types and counts", async () => { |
| 110 | + expect(await read("read_graph", { observationLimit: 0 })).toEqual({ |
| 111 | + entities: [ |
| 112 | + { ...alice, observations: [], observationCount: 3 }, |
| 113 | + { ...bob, observations: [], observationCount: 1 }, |
| 114 | + { ...acme, observations: [], observationCount: 2 }, |
| 115 | + { ...empty, observationCount: 0 }, |
| 116 | + ], |
| 117 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 118 | + }); |
| 119 | + }); |
| 120 | + |
| 121 | + it("keeps the first observations, in the order they were added", async () => { |
| 122 | + expect(await read("read_graph", { observationLimit: 2 })).toEqual({ |
| 123 | + entities: [ |
| 124 | + { |
| 125 | + ...alice, |
| 126 | + observations: ["works at Acme Corp", "likes tea"], |
| 127 | + observationCount: 3, |
| 128 | + }, |
| 129 | + { ...bob, observationCount: 1 }, |
| 130 | + { ...acme, observationCount: 2 }, |
| 131 | + { ...empty, observationCount: 0 }, |
| 132 | + ], |
| 133 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 134 | + }); |
| 135 | + }); |
| 136 | + |
| 137 | + it("applies to search_nodes", async () => { |
| 138 | + expect( |
| 139 | + await read("search_nodes", { query: "acme", observationLimit: 1 }), |
| 140 | + ).toEqual({ |
| 141 | + entities: [ |
| 142 | + { |
| 143 | + ...alice, |
| 144 | + observations: ["works at Acme Corp"], |
| 145 | + observationCount: 3, |
| 146 | + }, |
| 147 | + { ...acme, observations: ["makes anvils"], observationCount: 2 }, |
| 148 | + ], |
| 149 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 150 | + }); |
| 151 | + }); |
| 152 | + |
| 153 | + it("applies to open_nodes", async () => { |
| 154 | + expect( |
| 155 | + await read("open_nodes", { |
| 156 | + names: ["Alice", "Missing"], |
| 157 | + observationLimit: 1, |
| 158 | + }), |
| 159 | + ).toEqual({ |
| 160 | + entities: [ |
| 161 | + { |
| 162 | + ...alice, |
| 163 | + observations: ["works at Acme Corp"], |
| 164 | + observationCount: 3, |
| 165 | + }, |
| 166 | + ], |
| 167 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 168 | + }); |
| 169 | + }); |
| 170 | + |
| 171 | + it.each([ |
| 172 | + ["read_graph", {}], |
| 173 | + ["search_nodes", { query: "a" }], |
| 174 | + ["open_nodes", { names: ["Alice"] }], |
| 175 | + ])("%s rejects a negative or fractional limit", async (name, args) => { |
| 176 | + expect(await rejected(name, { ...args, observationLimit: -1 })).toContain( |
| 177 | + "observationLimit", |
| 178 | + ); |
| 179 | + expect( |
| 180 | + await rejected(name, { ...args, observationLimit: 1.5 }), |
| 181 | + ).toContain("observationLimit"); |
| 182 | + }); |
| 183 | + }); |
| 184 | + |
| 185 | + describe("read_graph entityTypes", () => { |
| 186 | + it("keeps entities of the given types and the relations that touch them", async () => { |
| 187 | + expect( |
| 188 | + await read("read_graph", { entityTypes: ["organization"] }), |
| 189 | + ).toEqual({ |
| 190 | + entities: [acme], |
| 191 | + relations: [aliceWorksAtAcme], |
| 192 | + }); |
| 193 | + }); |
| 194 | + |
| 195 | + it("accepts several types, and combines with observationLimit", async () => { |
| 196 | + expect( |
| 197 | + await read("read_graph", { |
| 198 | + entityTypes: ["organization", "placeholder"], |
| 199 | + observationLimit: 0, |
| 200 | + }), |
| 201 | + ).toEqual({ |
| 202 | + entities: [ |
| 203 | + { ...acme, observations: [], observationCount: 2 }, |
| 204 | + { ...empty, observationCount: 0 }, |
| 205 | + ], |
| 206 | + relations: [aliceWorksAtAcme], |
| 207 | + }); |
| 208 | + }); |
| 209 | + |
| 210 | + it("matches types exactly", async () => { |
| 211 | + expect(await read("read_graph", { entityTypes: ["Person"] })).toEqual({ |
| 212 | + entities: [], |
| 213 | + relations: [], |
| 214 | + }); |
| 215 | + }); |
| 216 | + |
| 217 | + it("rejects an empty list", async () => { |
| 218 | + expect(await rejected("read_graph", { entityTypes: [] })).toContain( |
| 219 | + "entityTypes", |
| 220 | + ); |
| 221 | + }); |
| 222 | + }); |
| 223 | + |
| 224 | + describe("search_nodes limit", () => { |
| 225 | + it("keeps the first matches and the relations that touch them", async () => { |
| 226 | + expect(await read("search_nodes", { query: "acme", limit: 1 })).toEqual({ |
| 227 | + entities: [alice], |
| 228 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 229 | + }); |
| 230 | + expect(await read("search_nodes", { query: "o", limit: 2 })).toEqual({ |
| 231 | + entities: [alice, bob], |
| 232 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 233 | + }); |
| 234 | + }); |
| 235 | + |
| 236 | + it("returns every match when the limit exceeds them", async () => { |
| 237 | + expect(await read("search_nodes", { query: "acme", limit: 10 })).toEqual({ |
| 238 | + entities: [alice, acme], |
| 239 | + relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice], |
| 240 | + }); |
| 241 | + }); |
| 242 | + |
| 243 | + it("rejects a limit below 1", async () => { |
| 244 | + expect( |
| 245 | + await rejected("search_nodes", { query: "a", limit: 0 }), |
| 246 | + ).toContain("limit"); |
| 247 | + }); |
| 248 | + }); |
| 249 | +}); |
0 commit comments