@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/mcp-server-registry.test.ts

@@ -0,0 +1,146 @@
+/**
+ * `LiteLLM.MCPServer`: the list is the proxy's in-memory REGISTRY, not the table, so a row missing
+ * from it can still be live.
+ *
+ * ⛔ MEASURED 2026-09-29 by reading the live 1.103.0 container: `GET /v1/mcp/server` answers
+ *   `global_mcp_server_manager`'s registry, which `reload_servers_from_database` fills only from rows
+ *   whose approval status is null, active or approved and skips a row whose build throws; the caller's
+ *   key can narrow it too; and `add_mcp_server` only LOGS a failed registry refresh after the row is
+ *   committed. The by-id `GET` reads the table first and registers what it finds; `DELETE` acts on
+ *   the table. So absence from the list proves nothing, and these tests hold the resource to that.
+ * ★ EVERY VALUE IS `FAKE-*` or an RFC 2606 host.
+ */
+import { describe, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE } from './fake-litellm.ts';
+import {
+  type FakeMcpLitellm,
+  type FakeMcpOptions,
+  serverRow,
+  startFakeMcpLitellm,
+} from './fake-mcp-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMMCPServer, mcpServerHandlers } from './mcp-server.ts';
+import { deleteMcpServer, readMcpServer } from './mcp-server-operations.ts';
+import type { McpServerProps } from './mcp-server-types.ts';
+
+const KEY = 'sk-test-master';
+
+const run = <A, E>(fetchFn: typeof globalThis.fetch, effect: Effect.Effect<A, E, unknown>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+const stack = (fake: FakeMcpLitellm) => fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const start = (options: FakeMcpOptions = {}) => startFakeMcpLitellm({ masterKey: KEY, ...options });
+const props: McpServerProps = {
+  authType: 'none',
+  serverName: 'FAKE_docs',
+  transport: 'http',
+  url: 'https://mcp.example.com/mcp',
+};
+const row = serverRow({
+  server_id: 'FAKE-uuid-1',
+  server_name: 'FAKE_docs',
+  url: 'https://mcp.example.com/mcp',
+});
+
+describe('delete does not trust the list', () => {
+  test('a live row the registry lacks is still deleted', async () => {
+    const fake = start({ registryMisses: ['FAKE-uuid-1'], seed: [row] });
+    expect(await run(fake.fetch, deleteMcpServer('FAKE-uuid-1'))).toBeUndefined();
+    expect(fake.servers()).toEqual([]);
+    expect(writesOf(fake.requests())).toEqual(['DELETE /v1/mcp/server/FAKE-uuid-1']);
+  });
+
+  test('a row already gone is done: the DELETE is sent, its 404 is confirmed by the table read', async () => {
+    const fake = start();
+    await run(fake.fetch, deleteMcpServer('FAKE-never'));
+    expect(fake.requests().map((call) => `${call.method} ${call.path}`)).toEqual([
+      'DELETE /v1/mcp/server/FAKE-never',
+      'GET /v1/mcp/server/FAKE-never',
+    ]);
+  });
+
+  test('a refused delete of a row the registry lacks fails, and the row stays live', async () => {
+    const fake = start({ forbidDelete: true, registryMisses: ['FAKE-uuid-1'], seed: [row] });
+    await expect(run(fake.fetch, deleteMcpServer('FAKE-uuid-1'))).rejects.toThrow();
+    expect(fake.servers()).toHaveLength(1);
+  });
+
+  test('a refused delete whose confirming read also fails re-raises the original, never done', async () => {
+    const fake = start({ forbidDelete: true, readFails: true, seed: [row] });
+    await expect(run(fake.fetch, deleteMcpServer('FAKE-uuid-1'))).rejects.toThrow();
+    // a read that cannot say is not absence, even for an id the proxy does not have
+    const gone = start({ forbidDelete: true, readFails: true });
+    await expect(run(gone.fetch, deleteMcpServer('FAKE-never'))).rejects.toThrow();
+  });
+});
+
+describe('the by-id read', () => {
+  test('answers the row, and undefined for a missing id', async () => {
+    const fake = start({ seed: [row] });
+    expect((await run(fake.fetch, readMcpServer('FAKE-uuid-1')))?.server_id).toBe('FAKE-uuid-1');
+    expect(await run(fake.fetch, readMcpServer('FAKE-never'))).toBeUndefined();
+  });
+
+  test('an id that is another server’s NAME reads as absent, never as that server', async () => {
+    // ⚠️ measured: with no table row, `fetch_mcp_server` falls back to a lookup by name or alias
+    const fake = start({ seed: [row] });
+    expect(await run(fake.fetch, readMcpServer('FAKE_docs'))).toBeUndefined();
+  });
+
+  test('any failure but "not found" propagates instead of reading as absence', async () => {
+    const fake = start({ readFails: true, seed: [row] });
+    await expect(run(fake.fetch, readMcpServer('FAKE-uuid-1'))).rejects.toThrow();
+  });
+});
+
+describe('a row the registry lacks is found by id, so it is never created again', () => {
+  test('a create whose registry refresh failed reads back from the table and records the row', async () => {
+    const fake = start({ hideCreated: true });
+    const engine = stack(fake);
+    const declare = Effect.asVoid(LiteLLMMCPServer('Docs', props));
+    expect(await engine.deploy(declare)).toEqual({ Docs: 'create' });
+    expect(writesOf(fake.requests())).toHaveLength(1);
+    // the by-id read registered the row, and the next deploy neither POSTs nor updates
+    expect(await engine.deploy(declare)).toEqual({ Docs: 'noop' });
+    expect(writesOf(fake.requests())).toHaveLength(1);
+  });
+
+  test('adopting a pinned row the registry lacks writes nothing, where a POST would answer 400 "already exists"', async () => {
+    const fake = start({ registryMisses: ['FAKE-uuid-1'], seed: [row] });
+    const declare = Effect.asVoid(LiteLLMMCPServer('Docs', { ...props, serverId: 'FAKE-uuid-1' }));
+    expect(await stack(fake).deploy(declare, { adopt: true })).toEqual({ Docs: 'adopted' });
+    expect(writesOf(fake.requests())).toEqual([]);
+  });
+
+  test('a refresh read of an owned row the registry lacks returns it, not undefined', async () => {
+    const fake = start({ registryMisses: ['FAKE-uuid-1'], seed: [row] });
+    const output = {
+      alias: null,
+      allowAllKeys: false,
+      allowedTools: [],
+      authType: 'none',
+      credentialSeal: '',
+      description: null,
+      mcpAccessGroups: [],
+      serverId: 'FAKE-uuid-1',
+      serverName: 'FAKE_docs',
+      transport: 'http',
+      url: 'https://mcp.example.com/mcp',
+    };
+    const read = await run(
+      fake.fetch,
+      mcpServerHandlers.read({ id: 'Docs', instanceId: 'i', olds: props, output }),
+    );
+    expect(read).toMatchObject({ serverId: 'FAKE-uuid-1' });
+  });
+});

package/src/litellm/mcp-server-retype.test.ts

@@ -0,0 +1,114 @@
+/**
+ * `LiteLLM.MCPServer`: changing a server's auth type, through Alchemy's real Plan and Apply.
+ *
+ * ⛔ LITELLM WIPES THE STORED CREDENTIAL ON AN AUTH-CLASS CHANGE THAT SENDS NONE. Read from the live
+ *   1.103.0 container (`mcp_server/db.py` lines 1013-1014; `_credential_auth_class` keeps every
+ *   static type in its own class) and modelled by the fake as its one MEASURED rule. A resource that
+ *   let such an edit through with the variable unset would leave the row with no credential while
+ *   its seal still matched the old value, so the next deploy would call it converged and stay so.
+ * ★ EVERY VALUE IS `FAKE-*`, set and removed through the environment like a deploying process.
+ */
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { type FakeMcpLitellm, serverRow, startFakeMcpLitellm } from './fake-mcp-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMMCPServer } from './mcp-server.ts';
+import type { McpServerProps } from './mcp-server-types.ts';
+
+const KEY = 'sk-test-master';
+const VARIABLE = 'FAKE_MCP_RETYPE_TOKEN';
+
+const stack = (fake: FakeMcpLitellm) => fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: McpServerProps) => Effect.asVoid(LiteLLMMCPServer('Keyed', props));
+
+const bearer: McpServerProps = {
+  authType: 'bearer_token',
+  authValue: { fromEnv: VARIABLE },
+  serverName: 'FAKE_keyed',
+  transport: 'http',
+  url: 'https://keyed.example.com/mcp',
+};
+const keyed: McpServerProps = { ...bearer, authType: 'api_key' };
+
+const message = (failure: Promise<unknown>) =>
+  failure.then(
+    () => undefined,
+    (error: unknown) => String(error),
+  );
+
+beforeEach(() => {
+  process.env[VARIABLE] = 'FAKE-token-one';
+});
+afterEach(() => {
+  delete process.env[VARIABLE];
+});
+
+test('between two static types with the variable unset: refused, names it, writes nothing, keeps the credential', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const engine = stack(fake);
+  await engine.deploy(declare(bearer));
+  delete process.env[VARIABLE];
+  const before = fake.requests().length;
+  const failure = await message(engine.deploy(declare(keyed)));
+  expect(failure).toContain(VARIABLE);
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+  expect(fake.servers()[0]).toMatchObject({
+    auth_type: 'bearer_token',
+    credentials: { auth_value: 'FAKE-token-one' },
+  });
+});
+
+test('the refused switch is recoverable: with the variable set again the credential is written, then a no-op', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const engine = stack(fake);
+  await engine.deploy(declare(bearer));
+  delete process.env[VARIABLE];
+  await message(engine.deploy(declare(keyed)));
+  process.env[VARIABLE] = 'FAKE-token-two';
+  expect(await engine.deploy(declare(keyed))).toEqual({ Keyed: 'update' });
+  expect(fake.servers()[0]).toMatchObject({
+    auth_type: 'api_key',
+    credentials: { auth_value: 'FAKE-token-two' },
+  });
+  expect(await engine.deploy(declare(keyed))).toEqual({ Keyed: 'noop' });
+});
+
+test('between two static types with the variable set: the credential rides the same write, so nothing is wiped', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const engine = stack(fake);
+  await engine.deploy(declare(bearer));
+  expect(await engine.deploy(declare(keyed))).toEqual({ Keyed: 'update' });
+  expect(fake.bodies().at(-1)).toMatchObject({
+    auth_type: 'api_key',
+    credentials: { auth_value: 'FAKE-token-one' },
+  });
+  expect(fake.servers()[0]?.['credentials']).toEqual({ auth_value: 'FAKE-token-one' });
+  expect(await engine.deploy(declare(keyed))).toEqual({ Keyed: 'noop' });
+});
+
+test('adopting a row with no auth type as a static one demands the credential too', async () => {
+  const bare = serverRow({
+    server_id: 'FAKE-uuid-5',
+    server_name: 'FAKE_keyed',
+    url: 'https://keyed.example.com/mcp',
+  });
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [bare] });
+  delete process.env[VARIABLE];
+  const failure = await message(stack(fake).deploy(declare(bearer), { adopt: true }));
+  expect(failure).toContain(VARIABLE);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('an unchanged auth type with the variable unset is still updated, without touching the credential', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  const engine = stack(fake);
+  await engine.deploy(declare(bearer));
+  delete process.env[VARIABLE];
+  const before = fake.requests().length;
+  const described = { ...bearer, description: 'FAKE description' };
+  expect(await engine.deploy(declare(described))).toEqual({ Keyed: 'update' });
+  expect(fake.bodies().at(-1)).not.toHaveProperty('credentials');
+  expect(fake.servers()[0]?.['credentials']).toEqual({ auth_value: 'FAKE-token-one' });
+  expect(writesOf(fake.requests().slice(before))).toHaveLength(1);
+});

package/src/litellm/mcp-server-shadow.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `LiteLLM.MCPServer`: a `description` that `mcp_info.description` would hide is refused before any
+ * write (mcp-server-shadow.ts says why).
+ *
+ * ⛔ MEASURED 2026-09-29, read only: the list answers `mcp_info.description` when that KEY exists,
+ *   else the description column, and the resource writes only the column. Live, `Memos_CF` has the key
+ *   holding a JSON null with a NULL column, and `linear` has both as strings. The fake models the list
+ *   rule, so a write to such a row lands in the column and the list keeps answering the old value.
+ * ★ EVERY VALUE IS `FAKE-*` or an RFC 2606 host.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { type FakeMcpLitellm, serverRow, startFakeMcpLitellm } from './fake-mcp-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMMCPServer } from './mcp-server.ts';
+import type { McpServerProps } from './mcp-server-types.ts';
+
+const KEY = 'sk-test-master';
+
+const stack = (fake: FakeMcpLitellm) => fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: McpServerProps) => Effect.asVoid(LiteLLMMCPServer('Notes', props));
+const base: McpServerProps = {
+  authType: 'none',
+  serverName: 'FAKE_notes',
+  transport: 'http',
+  url: 'https://notes.example.com/mcp',
+};
+const held = (over: Record<string, unknown>) =>
+  serverRow({
+    server_id: 'FAKE-notes-id',
+    server_name: 'FAKE_notes',
+    url: 'https://notes.example.com/mcp',
+    ...over,
+  });
+const failure = (promise: Promise<unknown>) =>
+  promise.then(
+    () => undefined,
+    (error: unknown) => String(error),
+  );
+
+describe('a row whose mcp_info has a description key', () => {
+  test.each([
+    ['a null one (the Memos_CF shape)', { description: null, mcp_info: { description: null } }],
+    [
+      'a different string (the linear shape)',
+      { description: 'FAKE old', mcp_info: { description: 'FAKE old' } },
+    ],
+  ])('%s: the declared description is refused, and nothing is written', async (_label, fields) => {
+    const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [held(fields)] });
+    const message = await failure(
+      stack(fake).deploy(declare({ ...base, description: 'FAKE new' }), { adopt: true }),
+    );
+    expect(message).toContain('LitellmMcpServerDescriptionShadowedError');
+    expect(writesOf(fake.requests())).toEqual([]);
+  });
+
+  test('the same description is not a difference, so nothing is read or written', async () => {
+    const fake = startFakeMcpLitellm({
+      masterKey: KEY,
+      seed: [held({ description: 'FAKE same', mcp_info: { description: 'FAKE same' } })],
+    });
+    const engine = stack(fake);
+    await engine.deploy(declare({ ...base, description: 'FAKE same' }), { adopt: true });
+    expect(writesOf(fake.requests())).toEqual([]);
+  });
+
+  test('no description declared: the row is adopted and its description left alone', async () => {
+    const fake = startFakeMcpLitellm({
+      masterKey: KEY,
+      seed: [held({ mcp_info: { description: null } })],
+    });
+    await stack(fake).deploy(declare(base), { adopt: true });
+    expect(writesOf(fake.requests())).toEqual([]);
+  });
+});
+
+describe('a row without one', () => {
+  test('a declared description is written to the column and read back', async () => {
+    const fake = startFakeMcpLitellm({
+      masterKey: KEY,
+      seed: [held({ description: 'FAKE old', mcp_info: { server_name: 'FAKE_notes' } })],
+    });
+    const engine = stack(fake);
+    await engine.deploy(declare({ ...base, description: 'FAKE new' }), { adopt: true });
+    expect(fake.servers()[0]).toMatchObject({ description: 'FAKE new' });
+    expect(await engine.deploy(declare({ ...base, description: 'FAKE new' }))).toEqual({
+      Notes: 'noop',
+    });
+  });
+});

package/src/litellm/mcp-server-shadow.ts

@@ -0,0 +1,45 @@
+/**
+ * The one description this resource cannot write: a row whose `mcp_info` already has a
+ * `description` key.
+ *
+ * ⛔ MEASURED 2026-09-29 on the live 1.103.0 container and its database (read only): the list route
+ *   builds each row's `description` from `mcp_info.get("description")` (`_build_mcp_server_table`),
+ *   and registering a row copies the `description` COLUMN into `mcp_info` only when the KEY IS ABSENT
+ *   from `mcp_info` (`build_mcp_server_from_table`, `"description" not in mcp_info`). This resource
+ *   writes the column and models no `mcp_info`, so on a row whose `mcp_info` has the key, a declared
+ *   description lands in the column and is never read back, and every deploy would fail
+ *   `LitellmMcpServerNotConvergedError` after the write. Live: 2 of the 9 rows in
+ *   `LiteLLM_MCPServerTable` have the key: `linear` (a string, with the same length as its column)
+ *   and `Memos_CF` (a JSON null, with a NULL column). A key holding null shadows the column too.
+ * ★ THE ROW IS READ BY ID FROM THE TABLE, because the list's `mcp_info` already has the column
+ *   folded in: a description in it could be either, and only the table row tells them apart.
+ * ⚠️ Not `mcp_info` merging: a sent `mcp_info` REPLACES the stored one, and the list's copy carries
+ *   fields the proxy adds on the way out (`is_public`), which would be persisted.
+ */
+import * as Effect from 'effect/Effect';
+import { LitellmMcpServerDescriptionShadowedError } from './mcp-server-errors.ts';
+import { readMcpServer } from './mcp-server-operations.ts';
+import type { McpServerProps } from './mcp-server-types.ts';
+
+/** Fails BEFORE any write when the declared description would be hidden by the row's `mcp_info`. */
+export const refuseShadowedDescription = (props: McpServerProps, serverId: string) =>
+  props.description === undefined
+    ? Effect.void
+    : readMcpServer(serverId).pipe(
+        Effect.flatMap((row) => {
+          const info = row?.mcp_info;
+          const shadowed =
+            info !== undefined &&
+            info !== null &&
+            'description' in info &&
+            info['description'] !== props.description;
+          return shadowed
+            ? Effect.fail(
+                new LitellmMcpServerDescriptionShadowedError({
+                  serverId,
+                  serverName: props.serverName,
+                }),
+              )
+            : Effect.void;
+        }),
+      );

package/src/litellm/mcp-server-tools.test.ts

@@ -0,0 +1,85 @@
+/**
+ * `LiteLLM.MCPServer`: the tool whitelist (`allowedTools`) through Alchemy's real Plan and Apply.
+ *
+ * ⛔ AN EMPTY LIST IS THE OPEN STATE, NOT A CLOSED ONE. On the live 1.103.0 container a row with no
+ *   `mcp_info` enforce flag and an empty `allowed_tools` returns every tool (`server.py` lines
+ *   1692-1698, `mcp_server/utils.py`'s `server_applies_tool_allowlist`), so a resource that sent `[]`
+ *   for an undeclared list would switch a live whitelist off when the row is adopted. Undeclared
+ *   means "leave it"; only a declared list, `[]` included, is compared and sent.
+ * ★ EVERY VALUE IS `FAKE-*` or an RFC 2606 host.
+ */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { type FakeMcpLitellm, serverRow, startFakeMcpLitellm } from './fake-mcp-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMMCPServer } from './mcp-server.ts';
+import type { McpServerProps } from './mcp-server-types.ts';
+
+const KEY = 'sk-test-master';
+const TOOLS = ['FAKE_read', 'FAKE_write', 'FAKE_search'];
+
+const stack = (fake: FakeMcpLitellm) => fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: McpServerProps) => Effect.asVoid(LiteLLMMCPServer('Bindings', props));
+
+/** A live row with a whitelist, like an adopted `Cloudflare_Bindings`. */
+const whitelisted = serverRow({
+  allowed_tools: TOOLS,
+  auth_type: 'oauth2',
+  server_id: 'FAKE-uuid-3',
+  server_name: 'FAKE_bindings',
+  transport: 'http',
+  url: 'https://bindings.example.com/mcp',
+});
+const withoutList: McpServerProps = {
+  authType: 'oauth2',
+  serverName: 'FAKE_bindings',
+  transport: 'http',
+  url: 'https://bindings.example.com/mcp',
+};
+
+test('adopting a whitelisted row without restating its list keeps the whitelist and writes nothing', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [whitelisted] });
+  const planned = await stack(fake).deploy(declare(withoutList), { adopt: true });
+  expect(Object.values(planned)).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(fake.servers()[0]?.['allowed_tools']).toEqual(TOOLS);
+});
+
+test('a grant that must change on such a row is corrected without sending the list', async () => {
+  const open = serverRow({ ...whitelisted, allow_all_keys: true });
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [open] });
+  const planned = await stack(fake).deploy(declare(withoutList), { adopt: true });
+  // ⚠️ Alchemy's adoption branch plans `adopted` even when reconcile then writes: no `update` shows
+  expect(Object.values(planned)).toEqual(['adopted']);
+  expect(fake.bodies()).toHaveLength(1);
+  expect(fake.bodies()[0]).toMatchObject({ allow_all_keys: false });
+  expect(fake.bodies()[0]).not.toHaveProperty('allowed_tools');
+  expect(fake.servers()[0]).toMatchObject({ allow_all_keys: false, allowed_tools: TOOLS });
+});
+
+test('a declared list is authoritative: it replaces the live one, order and repeats aside', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [whitelisted] });
+  const engine = stack(fake);
+  const same = { ...withoutList, allowedTools: [...TOOLS].reverse() };
+  await engine.deploy(declare(same), { adopt: true });
+  expect(writesOf(fake.requests())).toEqual([]);
+
+  const narrower = { ...withoutList, allowedTools: ['FAKE_read'] };
+  expect(await engine.deploy(declare(narrower))).toEqual({ Bindings: 'update' });
+  expect(fake.bodies().at(-1)).toMatchObject({ allowed_tools: ['FAKE_read'] });
+  expect(fake.servers()[0]?.['allowed_tools']).toEqual(['FAKE_read']);
+});
+
+test('a declared empty list is sent as it is: an explicit "no restriction", never an accident', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [whitelisted] });
+  await stack(fake).deploy(declare({ ...withoutList, allowedTools: [] }), { adopt: true });
+  expect(fake.bodies()[0]).toMatchObject({ allowed_tools: [] });
+  expect(fake.servers()[0]?.['allowed_tools']).toEqual([]);
+});
+
+test('a create that declares no list sends none', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY });
+  expect(await stack(fake).deploy(declare(withoutList))).toEqual({ Bindings: 'create' });
+  expect(fake.bodies()[0]).not.toHaveProperty('allowed_tools');
+});

package/src/litellm/mcp-server-types.ts

@@ -0,0 +1,143 @@
+/**
+ * What a `LiteLLM.MCPServer` declares (props) and what is remembered about it (attributes).
+ *
+ * ⛔ NEITHER TYPE HOLDS A CREDENTIAL (S25). Alchemy persists props AND attributes in its state
+ *   store, and it does not encrypt them: `StateEncoding.ts` TAGS a `Redacted` value and writes the
+ *   inner value beside the tag (measured on alchemy 2.0.0-beta.79, `State/StateEncoding.ts` line
+ *   87-89). So a `Redacted<string>` prop would still land in state as plaintext. The credential is
+ *   declared as `{ fromEnv: 'NAME' }`; the NAME is what is stored, and the value lives only in the
+ *   deploying process (wrapped in `Redacted` there, `mcp-server-credential.ts`) and on the wire.
+ * ★ WHAT LITELLM STORES IS NEVER MIRRORED BACK. The list route carries `credentials`,
+ *   `static_headers`, `env` and `env_vars`; `toAttributes` (mcp-server-form.ts) copies none of them.
+ * ⚠️ NOT MODELLED, on purpose: `stdio` (it runs a command on the proxy host), the OAuth client
+ *   registration fields, `static_headers`/`extra_headers`, `mcp_info`, tool renames, BYOK and
+ *   the AWS / token-exchange auth types (each needs credential fields this resource does not
+ *   model). A row that uses them can still be adopted; what is not declared is left alone.
+ * ⚠️ NO `teams`. The create and edit requests of `@distilled.cloud/litellm` 0.3.0 (LiteLLM 1.103.0)
+ *   have no team field; `teams` exists only on the row a read returns. Team access is granted on
+ *   the team side (its `object_permission`), which is a different resource.
+ */
+import type { FromEnv } from '../secrets/write-only.ts';
+
+/** `stdio` is refused by the type: it would run a declared command on the proxy host. */
+export type McpTransport = 'sse' | 'http';
+
+/**
+ * Auth types that carry ONE static credential (`credentials.auth_value` on the wire). Which header
+ * each one becomes is LiteLLM's, not this package's (unmeasured here).
+ */
+export type McpStaticAuthType = 'api_key' | 'bearer_token' | 'basic' | 'authorization' | 'token';
+
+/** `oauth2` is a per-user flow LiteLLM runs itself: no static credential is declared for it. */
+export type McpAuthType = 'none' | 'oauth2' | McpStaticAuthType;
+
+export interface McpServerProps {
+  /**
+   * The server's name, and the way an existing row is ADOPTED: the live row whose `server_name`
+   * equals it. Changing it is an update of the same row, never a replace. The update re-sends the
+   * live alias, so the tool prefix stays. Declare `alias` to change the prefix.
+   */
+  readonly serverName: string;
+  /**
+   * Pins the live row (adopts by id) or chooses the id a create asks for. Without it, a live row
+   * is found by `serverName` and a new one gets a deterministic physical name. ⛔ A DIFFERENT
+   * DECLARED ID IS A REPLACE (create-first, so the old row is only removed by an opt-in
+   * `RemovalPolicy.destroy()`).
+   */
+  readonly serverId?: string;
+  /**
+   * The tool prefix LiteLLM shows (`<alias>-<tool>`). Compared only when declared, and an
+   * undeclared live alias is KEPT: an update that sends a `serverName` with no alias would make
+   * LiteLLM rewrite the alias to the name, so the live one is re-sent (mcp-server-form.ts).
+   * Declare this to change the prefix; a changed `serverName` does not. ⛔ Must match
+   * `^[A-Za-z0-9._]{1,128}$` (same rule as `serverName`): LiteLLM 1.103 runs `validate_tool_name`
+   * on it, so a space, `/`, `:`, `@` or more than 128 characters is a 400 only at apply.
+   */
+  readonly alias?: string;
+  /**
+   * The upstream MCP endpoint, `http` or `https`. ⛔ Refused if it carries userinfo, a fragment or
+   * a secret-looking query parameter (`?token=…`): the URL is a prop, so it lands in state. Declare
+   * the credential as `authValue` instead.
+   */
+  readonly url: string;
+  /** `sse` or `http`. Required: LiteLLM's own default is not this resource's to fix silently. */
+  readonly transport: McpTransport;
+  /** Required: a default would silently choose "no authentication". */
+  readonly authType: McpAuthType;
+  /**
+   * The static credential for a `McpStaticAuthType`, by the NAME of the environment variable that
+   * holds it. Required for those types and refused for the others.
+   */
+  readonly authValue?: FromEnv;
+  /**
+   * Compared only when declared. ⚠️ A blank one (`''` or whitespace) is refused: LiteLLM copies the
+   * column into `mcp_info` only when the value is truthy, so it would never converge. LiteLLM's
+   * list answers `mcp_info.description` in preference to this column, and this resource writes only
+   * the column. A row whose `mcp_info` has a `description` key (even a null one) that differs from
+   * the declaration is refused (`LitellmMcpServerDescriptionShadowedError`) rather than written and
+   * failed on the read back.
+   */
+  readonly description?: string;
+  /**
+   * Whether EVERY virtual key may call this server. Always compared, default `false`: it is an
+   * access grant, so an adopted row that has it on is corrected, never left open silently.
+   */
+  readonly allowAllKeys?: boolean;
+  /**
+   * The tools a caller may use, compared as a set. ⛔ COMPARED AND SENT ONLY WHEN DECLARED: omitted
+   * leaves the live whitelist exactly as it is. ⚠️ `[]` is NOT "closed" — at 1.103.0 an empty list
+   * turns the whitelist off (every tool is returned) unless the row's `mcp_info` carries the enforce
+   * flag, which this resource does not model. Declare `[]` only to mean "no restriction".
+   */
+  readonly allowedTools?: readonly string[];
+  /** Access groups this server belongs to. Always compared (as a set). */
+  readonly mcpAccessGroups?: readonly string[];
+}
+
+export interface McpServerAttributes {
+  readonly serverId: string;
+  readonly serverName: string | null;
+  readonly alias: string | null;
+  /** ⛔ REDACTED on the way in (userinfo and secret-looking query values become `REDACTED`). */
+  readonly url: string | null;
+  readonly transport: string;
+  /** `none` when the live row carries no auth type. */
+  readonly authType: string;
+  readonly description: string | null;
+  readonly allowAllKeys: boolean;
+  readonly allowedTools: readonly string[];
+  readonly mcpAccessGroups: readonly string[];
+  /**
+   * `scrypt:<salt>:<digest>` of the credential last written, or `''`. ⛔ Never the value. LiteLLM
+   * does not return a credential to compare with, so this is how a plan notices a rotated one
+   * (secrets/write-only.ts). It is carried from the previous state, never read from the row.
+   */
+  readonly credentialSeal: string;
+}
+
+/** Whether a value is not a string with something in it. Takes `unknown`: a declaration can say anything. */
+export const isBlank = (value: unknown): boolean =>
+  typeof value !== 'string' || value.trim() === '';
+
+const STATIC: ReadonlySet<string> = new Set<McpStaticAuthType>([
+  'api_key',
+  'bearer_token',
+  'basic',
+  'authorization',
+  'token',
+]);
+
+/** Whether an auth type carries one static credential. Takes a string: a live row can say anything. */
+export const isStaticAuthType = (authType: string): boolean => STATIC.has(authType);
+
+export const AUTH_TYPES: readonly McpAuthType[] = [
+  'none',
+  'oauth2',
+  'api_key',
+  'bearer_token',
+  'basic',
+  'authorization',
+  'token',
+];
+
+export const TRANSPORTS: readonly McpTransport[] = ['sse', 'http'];