@nimbus-dev/connectors 0.5.0 → 0.7.0

package/connectors/flagsmith/nimbus.extension.json

@@ -2,14 +2,14 @@
   "id": "com.nimbus.flagsmith",
   "displayName": "Flagsmith",
   "version": "0.1.0",
-  "description": "Flagsmith feature-flag connector (read-only). Surfaces feature-flag definitions across all projects — name, type, default-enabled, initial value, description, tags, archived state, owner count, and timestamps — into the local index as `flagsmith:feature_flag` items, useful for incident correlation (\"did this flag exist when the alert fired?\"). Admin-API-token auth (`Authorization: Token <token>`). Regional / self-hosted instances override `flagsmith.api_base` (default https://api.flagsmith.com); the SaaS API host (api.flagsmith.com) is the only one in the static sandbox manifest today. v1 indexes flag definitions only — per-environment on/off state + segments are a deferred follow-up. The `flagsmith.flag.toggle` write tool is a deferred Phase 8 follow-up.",
+  "description": "Flagsmith feature-flag connector. Surfaces feature-flag definitions across all projects — name, type, default-enabled, initial value, description, tags, archived state, owner count, and timestamps — into the local index as `flagsmith:feature_flag` items, useful for incident correlation (\"did this flag exist when the alert fired?\"). Admin-API-token auth (`Authorization: Token <token>`). Regional / self-hosted instances override `flagsmith.api_base` (default https://api.flagsmith.com); the SaaS API host (api.flagsmith.com) is the only one in the static sandbox manifest today. v1 indexes flag definitions only — per-environment on/off state + segments are a deferred follow-up. Write tool (needs owner approval): `flagsmith.feature.state.set` enables or disables a feature, optionally with a typed value, in ONE environment, through Flagsmith's experimental `__future__` endpoint; Flagsmith refuses it while change requests are enabled.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",
   "permissions": {
     "network": ["api.flagsmith.com"]
   },
-  "hitlRequired": [],
+  "hitlRequired": ["write"],
   "syncInterval": 600,
   "minNimbusVersion": "0.2.0"
 }

package/connectors/flagsmith/src/server.ts

@@ -1,6 +1,14 @@
-import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerFlagsmithTools } from "./tools.ts";
 
-await runReadOnlyMcpConnector("nimbus-flagsmith", (reg) => {
-  registerFlagsmithTools(reg);
-});
+const server = new McpServer(
+  { name: "nimbus-flagsmith", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
+
+registerFlagsmithTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/flagsmith/src/tools.ts

@@ -1,17 +1,52 @@
 import { z } from "zod";
-import { createJsonGetter, envAuthHeaders, optionalEnv } from "../../../shared/env-json-api.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
-import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createJsonGetter,
+  createJsonSender,
+  envAuthHeaders,
+  type JsonApiConfig,
+  optionalEnv,
+} from "../../../shared/env-json-api.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
 import { filterFlagsmithFeatures } from "./search-filter.ts";
 
 const DEFAULT_API_BASE = "https://api.flagsmith.com";
 
-const fsGet = createJsonGetter({
+/**
+ * `Authorization: Token <FLAGSMITH_TOKEN>` for reads and writes alike. Flagsmith's swagger lists
+ * this scheme ("tokenAuth", prefix "Token") on the `__future__` operations too, beside the
+ * organisation "Master API Key" scheme; the docs page for those operations shows `Api-Key`, which
+ * is that second scheme. One factory, so a switch is one line.
+ */
+const flagsmithHeaders = envAuthHeaders({ env: "FLAGSMITH_TOKEN", scheme: "Token" });
+
+const apiV1: JsonApiConfig = {
   // `optionalEnv`, not `optionalBaseUrl`: a trailing slash on the override is left as given.
   base: () => `${optionalEnv("FLAGSMITH_API_BASE", DEFAULT_API_BASE)}/api/v1`,
   label: "Flagsmith",
-  headers: envAuthHeaders({ env: "FLAGSMITH_TOKEN", scheme: "Token" }),
-});
+  headers: flagsmithHeaders,
+};
+
+/**
+ * The environment-level feature-state endpoints. EXPERIMENTAL ("may change without notice",
+ * https://docs.flagsmith.com/managing-flags/updating-flags). Why not the v1 route: Flagsmith's own
+ * repository calls `/api/v1/environments/{key}/featurestates/` "deprecated" (PR 8732, "the legacy
+ * feature state APIs"), the docs site documents only the `__future__` pair, and the v1 write needs
+ * a feature-state id looked up first. `__future__` takes the feature id directly. Isolated here so
+ * a change of path is one edit.
+ */
+const apiFuture: JsonApiConfig = {
+  ...apiV1,
+  base: () => `${optionalEnv("FLAGSMITH_API_BASE", DEFAULT_API_BASE)}/api/__future__`,
+};
+
+const fsGet = createJsonGetter(apiV1);
+const fsFutureGet = createJsonGetter(apiFuture);
+const fsFutureSend = createJsonSender(apiFuture);
 
 function featuresFromPage(root: unknown): unknown[] {
   if (Array.isArray(root)) {
@@ -26,9 +61,65 @@ export const FLAGSMITH_TOOL_NAMES = [
   "flagsmith_list",
   "flagsmith_get",
   "flagsmith_search",
+  "flagsmith_feature_state_get",
+  "flagsmith_feature_state_set",
 ] as const;
 
-export function registerFlagsmithTools(reg: ZodToolRegistrar): void {
+/** Segment overrides returned by a state read; the rest are counted, not shown (size bound). */
+const MAX_SEGMENT_OVERRIDES = 50;
+
+const featureStateArgs = z.object({
+  environmentKey: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "letters, digits, '_' and '-' only"),
+  featureId: z.number().int().min(1),
+});
+
+type FeatureStateArgs = z.infer<typeof featureStateArgs>;
+
+function statePath(p: FeatureStateArgs): string {
+  return `/environments/${encodeURIComponent(p.environmentKey)}/features/${String(p.featureId)}/`;
+}
+
+/** `{ environment_default, segment_overrides }` with the overrides capped and the cap disclosed. */
+async function readFeatureState(p: FeatureStateArgs): Promise<Record<string, unknown>> {
+  const raw = (await fsFutureGet(statePath(p))) as {
+    environment_default?: unknown;
+    segment_overrides?: unknown;
+  } | null;
+  const overrides = Array.isArray(raw?.segment_overrides) ? raw.segment_overrides : [];
+  return {
+    environment_default: raw?.environment_default,
+    segment_overrides: overrides.slice(0, MAX_SEGMENT_OVERRIDES),
+    ...(overrides.length > MAX_SEGMENT_OVERRIDES
+      ? { segmentOverridesNotShown: overrides.length - MAX_SEGMENT_OVERRIDES }
+      : {}),
+  };
+}
+
+const valueSchema = z.object({
+  type: z.enum(["string", "integer", "boolean"]),
+  value: z.string().max(20_000),
+});
+
+/** The typed value must parse as its type; checked in the handler, before any request. */
+function assertValueMatchesType(v: z.infer<typeof valueSchema>): void {
+  if (v.type === "integer" && !/^-?\d+$/.test(v.value)) {
+    throw new Error(`value ${JSON.stringify(v.value)} is not an integer; nothing was sent`);
+  }
+  if (v.type === "boolean" && v.value !== "true" && v.value !== "false") {
+    throw new Error(`value ${JSON.stringify(v.value)} is not true or false; nothing was sent`);
+  }
+}
+
+export function registerFlagsmithTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "flagsmith",
+    scopeEnv: "NIMBUS_MCP_FLAGSMITH_WRITE_SCOPE",
+    scopeKinds: ["flag"],
+  });
+
   reg(
     "flagsmith_list",
     "List Flagsmith projects, or feature flags for a project. Without `projectId`, returns the account's projects (`/projects/`). With `projectId`, returns that project's feature flags (`/projects/{projectId}/features/`), capped at `limit` (default 100).",
@@ -92,4 +183,53 @@ export function registerFlagsmithTools(reg: ZodToolRegistrar): void {
       return jsonResult({ matches });
     },
   );
+
+  reg(
+    "flagsmith_feature_state_get",
+    "Read one feature's state in ONE environment (`GET /api/__future__/environments/{environmentKey}/features/{featureId}/`, an EXPERIMENTAL Flagsmith endpoint): `environment_default` (enabled, typed value, variants) and `segment_overrides` (capped at 50, the remainder counted in `segmentOverridesNotShown`). Identity overrides are not covered.",
+    featureStateArgs,
+    async (p) => jsonResult(await readFeatureState(p)),
+  );
+
+  registerWriteTool(
+    "flagsmith_feature_state_set",
+    {
+      mutates: "flagsmith.feature.state.set",
+      // The previous state is recorded in the audit pre-state; this tool does not restore it.
+      recoverable: false,
+      capturePreState: readFeatureState,
+      scopeTargetOf: (p) => ({ kind: "flag", value: `${p.environmentKey}/${String(p.featureId)}` }),
+    },
+    "Enable or disable a feature in ONE environment, optionally setting its typed value (`PATCH /api/__future__/environments/{environmentKey}/features/{featureId}/`, an EXPERIMENTAL Flagsmith endpoint that may change without notice). Omitting `value` is intended to leave the value alone (PATCH merge semantics are unverified against a live server); segment and identity overrides are untouched. Flagsmith refuses it while change requests are enabled for the environment, with its own message. The result carries `confirmed`: true only when the reply shows the requested `enabled` and, when `value` was given, that value; false means the server accepted the write but its reply does not show the new state.",
+    featureStateArgs.extend({ enabled: z.boolean(), value: valueSchema.optional() }),
+    async (p) => {
+      // Validated here, not with `.refine`: a refined schema loses `.shape` (the registrar needs it).
+      if (p.value !== undefined) assertValueMatchesType(p.value);
+      const response = (await fsFutureSend("PATCH", statePath(p), {
+        environment_default: {
+          enabled: p.enabled,
+          ...(p.value === undefined ? {} : { value: p.value }),
+        },
+      })) as { environment_default?: { enabled?: unknown; value?: unknown } } | null;
+      const echoed = response?.environment_default;
+      // The value comes back as `{type, value}` like it is sent; its inner value may be typed or a
+      // string, so the string forms are compared, and a type the reply names must be the one sent.
+      const shown = echoed?.value as { type?: unknown; value?: unknown } | undefined;
+      const valueShown =
+        p.value === undefined ||
+        (shown !== undefined &&
+          shown !== null &&
+          String(shown.value) === p.value.value &&
+          (shown.type === undefined || shown.type === p.value.type));
+      return jsonResult({
+        ok: true,
+        environmentKey: p.environmentKey,
+        featureId: p.featureId,
+        // true only when the reply shows the state that was asked for; false means the server
+        // accepted the write but its reply does not show the new state.
+        confirmed: echoed?.enabled === p.enabled && valueShown,
+        enabled: echoed?.enabled,
+      });
+    },
+  );
 }

package/connectors/github/src/tools.ts

@@ -4,7 +4,15 @@ import {
   createWriteToolRegistrar,
   type WriteToolConfig,
 } from "../../../shared/consent-kit.ts";
-import { ghFetch, ghQueryPath, ghRepoPath, setGhPaging } from "../../../shared/github-rest.ts";
+import {
+  ghFetch,
+  ghQueryPath,
+  ghRepoPath,
+  isSafeGhSlug,
+  isSafeGitRef,
+  resolveCommitSha,
+  setGhPaging,
+} from "../../../shared/github-rest.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
@@ -35,6 +43,10 @@ export const GITHUB_TOOL_NAMES = [
   "github_ci_runs",
   "github_ci_run_get",
   "github_branch_delete",
+  "github_ref_get",
+  "github_branch_create",
+  "github_pr_create",
+  "github_pr_update",
   "github_tag_create",
   "github_commit_push",
 ] as const;
@@ -61,6 +73,11 @@ export function registerGithubTools(
   const registerGithubTool = makeRestToolRegistrar({ registrar: reg, ...githubRest });
   const registerRestWriteTool = makeRestWriteToolRegistrar({ registerWriteTool, ...githubRest });
 
+  const repoScope = (p: { owner: string; repo: string }): { kind: string; value: string } => ({
+    kind: "repo",
+    value: `${p.owner}/${p.repo}`,
+  });
+
   /**
    * The write-tool equivalent of `registerGithubTool`, routed through the write registrar.
    * `scopeTargetOf` is supplied here rather than per tool — every GitHub mutation is scoped to one
@@ -76,7 +93,7 @@ export function registerGithubTools(
   ): void {
     registerRestWriteTool(
       name,
-      { ...cfg, scopeTargetOf: (p) => ({ kind: "repo", value: `${p.owner}/${p.repo}` }) },
+      { ...cfg, scopeTargetOf: repoScope },
       description,
       schema,
       buildPath,
@@ -91,8 +108,8 @@ export function registerGithubTools(
   });
 
   const repoSlugArgs = z.object({
-    owner: z.string().min(1),
-    repo: z.string().min(1),
+    owner: z.string().refine(isSafeGhSlug, "not a valid GitHub owner name"),
+    repo: z.string().refine(isSafeGhSlug, "not a valid GitHub repository name"),
   });
 
   const githubRepoListSchema = z.object({
@@ -327,6 +344,119 @@ export function registerGithubTools(
     },
   );
 
+  /** A ref the model names reaches a URL path, so every one passes `isSafeGitRef` at the schema. */
+  const gitRefSchema = z.string().min(1).max(255).refine(isSafeGitRef, "not a safe git ref name");
+
+  const githubRefGetSchema = repoSlugArgs.extend({ ref: gitRefSchema });
+
+  reg(
+    "github_ref_get",
+    "Resolve a branch, tag or commit to its commit SHA (a bare name is tried as a branch, then a tag; an annotated tag resolves to its commit). Returns {ref, kind: branch|tag|sha, sha}.",
+    githubRefGetSchema,
+    async (parsed) => {
+      const token = requireProcessEnv("GITHUB_PAT");
+      const { sha, kind } = await resolveCommitSha(token, parsed.owner, parsed.repo, parsed.ref);
+      return jsonResult({ ref: parsed.ref, kind, sha });
+    },
+  );
+
+  const githubBranchCreateSchema = repoSlugArgs.extend({
+    branch: gitRefSchema,
+    fromRef: gitRefSchema,
+    expectedSha: z
+      .string()
+      .regex(/^[0-9a-f]{40}$/i)
+      .optional(),
+  });
+
+  registerWriteTool(
+    "github_branch_create",
+    // A new ref is undone by github_branch_delete, so there is nothing to capture first.
+    { mutates: "github.branch.create", recoverable: true, scopeTargetOf: repoScope },
+    "Create a branch from a branch, tag or commit (fromRef). If expectedSha is given and fromRef now resolves to a different commit, nothing is created.",
+    githubBranchCreateSchema,
+    async (parsed) => {
+      const token = requireProcessEnv("GITHUB_PAT");
+      const { sha } = await resolveCommitSha(token, parsed.owner, parsed.repo, parsed.fromRef);
+      if (parsed.expectedSha !== undefined && parsed.expectedSha.toLowerCase() !== sha) {
+        throw new Error(`fromRef resolves to ${sha}, not the approved ${parsed.expectedSha}`);
+      }
+      const ref = `refs/heads/${parsed.branch}`;
+      const res = await ghFetch(
+        token,
+        `${ghRepoPath(parsed.owner, parsed.repo)}/git/refs`,
+        jsonInit("POST", { ref, sha }),
+      );
+      if (!res.ok) {
+        throw new Error(`GitHub ${String(res.status)}: ${res.text.slice(0, 300)}`);
+      }
+      return jsonResult({ ok: true, ref, sha, fromRef: parsed.fromRef });
+    },
+  );
+
+  const githubPrCreateSchema = repoSlugArgs.extend({
+    head: z.string().min(1).max(255),
+    base: z.string().min(1).max(255),
+    title: z.string().min(1).max(256),
+    body: z.string().max(65_000).optional(),
+    draft: z.boolean().optional(),
+  });
+
+  registerGithubWriteTool(
+    "github_pr_create",
+    { mutates: "github.pr.create", recoverable: true },
+    "Open a pull request from head (a branch, or user:branch for a fork) into base. Title and body are sent exactly as given.",
+    githubPrCreateSchema,
+    (parsed) => `${ghRepoPath(parsed.owner, parsed.repo)}/pulls`,
+    (parsed) =>
+      jsonInit("POST", {
+        head: parsed.head,
+        base: parsed.base,
+        title: parsed.title,
+        ...(parsed.body === undefined ? {} : { body: parsed.body }),
+        ...(parsed.draft === undefined ? {} : { draft: parsed.draft }),
+      }),
+  );
+
+  // A plain object, not a `.refine()`d one: the registrar passes `.shape` as the MCP inputSchema and a
+  // refined object has none. The at-least-one check is the handler's.
+  const githubPrUpdateSchema = githubPrNumberSchema.extend({
+    title: z.string().min(1).max(256).optional(),
+    body: z.string().max(65_000).optional(),
+    base: z.string().min(1).max(255).optional(),
+  });
+  const prPath = (parsed: { owner: string; repo: string; pullNumber: number }): string =>
+    `${ghRepoPath(parsed.owner, parsed.repo)}/pulls/${String(parsed.pullNumber)}`;
+
+  registerGithubWriteTool(
+    "github_pr_update",
+    {
+      mutates: "github.pr.update",
+      // An edit overwrites text; its inverse needs the old text, so capture it first.
+      recoverable: false,
+      capturePreState: async (parsed) => {
+        const token = requireProcessEnv("GITHUB_PAT");
+        const res = await ghFetch(token, prPath(parsed));
+        const pr = res.json as { title?: unknown; body?: unknown; base?: { ref?: unknown } } | null;
+        if (!res.ok || pr === null) return { resolved: false, status: res.status };
+        return { title: pr.title, body: pr.body, base: pr.base?.ref };
+      },
+    },
+    "Edit a pull request's title, body or base branch (at least one). It never opens, closes or merges it.",
+    githubPrUpdateSchema,
+    prPath,
+    (parsed) => {
+      if (parsed.title === undefined && parsed.body === undefined && parsed.base === undefined) {
+        throw new Error("github_pr_update needs at least one of title, body, base");
+      }
+      return jsonInit("PATCH", {
+        ...(parsed.title === undefined ? {} : { title: parsed.title }),
+        ...(parsed.body === undefined ? {} : { body: parsed.body }),
+        ...(parsed.base === undefined ? {} : { base: parsed.base }),
+      });
+    },
+  );
+
   const githubTagCreateSchema = repoSlugArgs.extend({
     tag: z.string().min(1).max(255),
     sha: z.string().min(7).max(40),

package/connectors/github-actions/src/tools.ts

@@ -8,6 +8,7 @@ import {
   ghFetch,
   ghQueryPath,
   ghRepoPath,
+  isSafeGhSlug,
   setGhPaging,
 } from "../../../shared/github-rest.ts";
 import {
@@ -54,8 +55,8 @@ export function registerGithubActionsTools(
   });
 
   const repoSlugArgs = z.object({
-    owner: z.string().min(1),
-    repo: z.string().min(1),
+    owner: z.string().refine(isSafeGhSlug, "not a valid GitHub owner name"),
+    repo: z.string().refine(isSafeGhSlug, "not a valid GitHub repository name"),
   });
 
   const runListSchema = repoSlugArgs.extend({