@goodfellow-cms/mcp 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goodfellow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @goodfellow-cms/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Work on a [Goodfellow](https://goodfellow-cms.github.io/goodfellow-cms/) site from Claude. An [MCP](https://modelcontextprotocol.io) server with Goodfellow's tools: Claude reads a site's pages, items and settings, sees what blocks it has, makes changes in a draft, takes screenshots, and publishes the draft or submits it for review.
+
+Most editors use Goodfellow's hosted connector instead; see [Work with Claude](https://goodfellow-cms.github.io/goodfellow-cms/docs/claude). This package runs the same tools on your own computer, signed in with a GitHub or GitLab token that stays there.
+
+## Claude Code
+
+```sh
+claude mcp add goodfellow --env GOODFELLOW_SITE=github:your-name/your-site --env GOODFELLOW_TOKEN=your-token -- npx -y @goodfellow-cms/mcp
+```
+
+- `GOODFELLOW_SITE`: the site's repository, `github:owner/name` or `gitlab:group/name`.
+- `GOODFELLOW_TOKEN`: a token that can change the site's files and open pull requests or merge requests.
+- `GITLAB_URL`: for a GitLab of your own.
+- `GOODFELLOW_BROWSER`: a Chromium-based browser for screenshots, if not Google Chrome or Microsoft Edge.
+
+## Claude Desktop
+
+Install the [Goodfellow extension](https://goodfellow-cms.github.io/goodfellow-cms/goodfellow.mcpb), which `pnpm pack-extension` builds from this package.
+
+## In your own server
+
+`createGoodfellowServer()` gives an `McpServer` with the tools, for any transport:
+
+```ts
+import { createGoodfellowServer } from "@goodfellow-cms/mcp";
+
+const server = createGoodfellowServer({
+  sites: async () => [{ id: "github:your-name/your-site" }],
+  backend: async (site) => signInSomehow(site), // a GitBackend from @goodfellow-cms/github or @goodfellow-cms/gitlab
+});
+```
+
+Goodfellow's hosted connector (`packages/connector` in the repository) is built this way.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { ContentSource, GitBackend } from "@goodfellow-cms/core";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import "@puckeditor/core";
+//#region src/site.d.ts
+/** Where the tools find the sites they may edit, and sign in to them. */
+interface ConnectorContext {
+  /** The sites this connection may edit, such as `github:parish/site`. */
+  sites(): Promise<Array<{
+    id: string;
+    label?: string;
+  }>>;
+  /** Signs in to a site's repository. Throws `ToolError` for a site this connection may not edit. */
+  backend(site: string): Promise<GitBackend>;
+  /** Fetches the live site's description. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** Takes screenshots, where this server can. */
+  screenshots?: Screenshotter;
+  /** For tests. */
+  now?: () => Date;
+}
+interface Screenshotter {
+  /**
+   * A PNG of a page at `url`, `width` pixels wide and as tall as the page. With
+   * `preview`, `url` is the site's preview page (`/admin/#/preview`), which is
+   * handed a draft's content files and shows the page at `preview.path`.
+   */
+  take(options: {
+    url: string;
+    width: number;
+    preview?: {
+      files: Record<string, string>;
+      path: string;
+      dark?: boolean;
+    };
+    /** `url` is an image's, shown on a page of its own (`imagePage()`), no wider than `width`. */
+    image?: boolean;
+    /** Shows the page as a computer set to dark sees it, for sites with dark mode. */
+    dark?: boolean;
+  }): Promise<Uint8Array>;
+}
+//#endregion
+//#region src/content.d.ts
+/** Thrown with a message Claude can pass on to the editor as it is. */
+export declare class ToolError extends Error {
+  name: string;
+}
+/** Every content file, as text: what the preview page needs to show a draft as the site would. */
+export declare function contentFiles(source: ContentSource): Promise<Record<string, string>>;
+//#endregion
+//#region src/image-page.d.ts
+export declare function imagePage(url: string): string;
+//#endregion
+//#region src/tools.d.ts
+/** What Claude is told about working with Goodfellow sites. */
+export declare const INSTRUCTIONS = "These tools edit websites built with Goodfellow, for people who aren't developers.\n\n- Start with get_site, which lists the site's pages, collections and blocks.\n- Changes are saved in a draft, never straight to the live site. The first change starts one and returns its name: pass that name as \"draft\" to every later change and read, so they build on each other.\n- Pages, the header and the footer are made of blocks. get_blocks says which blocks the site has and what each one's props are. Blocks are written as a flat list in page order: a block inside another names it as \"parent\", and which of its places it goes in as \"slot\".\n- Show the editor what a draft looks like with screenshot before anything goes live.\n- Only publish when the editor says to. If they'd like someone to check it first, use submit_for_review instead.\n- Use the site's own words for things: say \"publish\", not \"commit\" or \"merge\".";
+//#endregion
+//#region src/index.d.ts
+/** A site's id for the tools: its host, then its repository, such as `github:parish/site`. */
+export type SiteId = `github:${string}` | `gitlab:${string}`;
+/** Splits a site's id into its host and repository, or `undefined` if it isn't one. */
+export declare function parseSiteId(id: string): {
+  host: "github" | "gitlab";
+  repo: string;
+} | undefined;
+/** An MCP server with Goodfellow's tools. Connect it to a transport. */
+export declare function createGoodfellowServer(context: ConnectorContext): McpServer;
+//#endregion
+export type { ConnectorContext, Screenshotter };