Extends Foldkit applications with server data synchronization, local-first state management, routing, and AI agent integration.
Also known as doeixd/foldkit-plus, foldkit-agent, foldkit-agent-mcp
- Stars
- 36
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is foldkit-plus MCP?
foldkit-plus extends Foldkit applications with server data synchronization, local-first state management, routing, and AI agent integration.
Summary generated from the project's README
About foldkit-plus MCP server
foldkit-plus provides a suite of packages designed to extend Foldkit applications by integrating them with external systems without fragmenting the central state machine. Instead of creating separate caches or stores, these tools ensure that server data, URL parameters, and local storage all remain synchronized with the primary Model and its update function. This approach allows developers to maintain a single source of truth for their application logic, making the system easier to test and reason about.
Developers can use specific packages like Remote for server-side facts, Sync and Durable for managing offline edits that must converge, and Mirror for linking Model slices to the URL or local storage. The toolkit also includes Agent for creating typed interfaces for AI assistants and Surface for defining public boundaries for features. By using these components, an application can support complex behaviors like multi-device synchronization, rich text editing, and interactive data grids while keeping all transitions within the original Schema-typed Model.
What you can do with it
- 1Synchronize offline data across devicesA developer can implement a system where multiple devices edit products offline and automatically reach agreement once they reconnect.
- 2Integrate AI agents into applicationsYou can expose specific application messages to an AI agent so it can perform tasks like adding or deleting items.
- 3Manage URL-based application stateDevelopers can link specific fields in the application model to URL parameters to enable deep linking and shareable views.
- 4Build collaborative rich text editorsThe framework supports multi-user editing where changes converge through a single journal.
Written from the project's README. Every use case is checked against a quote from it.
How to install foldkit-plus MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall foldkit-plus MCP in Claude Code
$ claude mcp add foldkit-plus -- npx -y foldkit-agentInstall foldkit-plus MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"foldkit-plus": {
"command": "npx",
"args": [
"-y",
"foldkit-agent"
]
}
}
}Install foldkit-plus MCP in VS Code
.vscode/mcp.json
{
"servers": {
"foldkit-plus": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"foldkit-agent"
]
}
}
}Install foldkit-plus MCP in VS Code CLI
$ code --add-mcp '{"name":"foldkit-plus","type":"stdio","command":"npx","args":["-y","foldkit-agent"]}'Install foldkit-plus MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"foldkit-plus": {
"command": "npx",
"args": [
"-y",
"foldkit-agent"
]
}
}
}Install foldkit-plus MCP in Codex
$ codex mcp add foldkit-plus -- npx -y foldkit-agentInstall foldkit-plus MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.foldkit-plus] command = "npx" args = ["-y", "foldkit-agent"]
Install foldkit-plus MCP in Gemini CLI
$ gemini mcp add -s user foldkit-plus npx -- -y foldkit-agentInstall foldkit-plus MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"foldkit-plus": {
"command": "npx",
"args": [
"-y",
"foldkit-agent"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledoeixd/foldkit-plus is public and reachablegithub.com/doeixd/foldkit-plus ↗Pass
- Package names this repository as its sourcefoldkit-agent, foldkit-agent-mcp name doeixd/foldkit-plus as sourcenpmjs.com/package/foldkit-agent ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for foldkit-agent, foldkit-agent-mcpnpmjs.com/package/foldkit-agent/v/0.12.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/doeixd/foldkit-plus ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from foldkit-agent, foldkit-agent-mcpPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubfoldkit-plus
Packages that extend a Foldkit application outward — to agents, servers, other devices, the URL, and design systems — without giving it a second place to keep state.
A Foldkit application is one state machine: a Schema-typed Model, a
Message union naming everything that can happen, and one pure update
function that turns a Message into the next Model and some Commands. That shape
is easy to reason about, test, and replay. It gets lost the moment an app grows a
cache in a hook, a store in the URL, a tool handler that re-implements a
transition, or a sync layer with its own reducer.
Everything in this repository keeps the one state machine. An agent can only
send Messages update already handles. Server data lives in the Model and is
reconciled by update. Replicas replay the same Messages through the same
update. The URL and local storage mirror a slice of the Model; they never own
one. Views are styled from outside without forking. Each package answers one
question, and they compose because they meet at explicit application boundaries.
The website: foldkit-plus.pages.dev has each package's guides and API reference, and the demos, each an example from this repository built as static files. Those with a server run it in your browser, shared by every tab, so nothing you do leaves it:
- A blog studio and its site (
examples/cms): Drafts beside the row, revisions, scheduled publishing and a page builder, with the public site rendered at build time. - Two devices, one registry (
examples/registry): Two devices edit 10,000 products in a data grid, offline and in conflict, and agree once both are back. - Pages two tabs edit at once (
examples/pages): Rich text two people edit at the same time, online or not, converging through one journal. - A rich text playground (
examples/richtext-playground): One document with movable blocks, anchored discussions, images, tables, code, toggles and footnotes, every edit a transition of the Model. - A todo list an agent can use (
examples/todo-app): One application definition drives the view, the tools an agent calls, the document replicas share, and the policy the server enforces. - A Twitter clone, Chirp (
examples/chirp): Posts declared once as Entities, guarded on the server, served through Remote, posted and edited through forms built from the same input, and liked in one round trip. - A data grid over 100,000 rows (
examples/data-grid): A grid that owns focus, selection, columns and the open editor, while the application owns every row. - Eight widgets from shared primitives (
examples/widgets): Once the capabilities exist, a family of widgets gets cheap: each one is a Bundle placement plus Behaviors on a shared Collection description, with no bespoke state machine.
Choose who owns the state
| What you are adding | Authoritative owner | Extension |
|---|---|---|
| Local UI state or a reusable widget | Parent Model and its update/child update | Bundle, Primitives |
| Facts loaded from a server | Server; the client cache is disposable | Remote |
| Offline edits that must converge | Client-authored operations in an authoritative journal order | Sync + Durable |
| Offline edits to rows a server owns | The journal; the table is its read model | Sync (/entity, /journal) + Remote |
| An interactive grid over the application's rows | The grid's Bundle for focus, selection and columns; the rows stay the application's | Data grid |
| A URL or remembered preference | Local Model; the external value is a representation | Mirror |
| Agent access or a customizable view | Existing state and transitions | Agent, Surface, Mixins |
A Surface can observe several owners. Observing a field does not grant a second package permission to change it outside its owning transition.
intent → Message → update → Model → Projection / Surface → consumer
|
└→ Command → result Message → update
Sixty seconds of code
Start with one mechanism: an inspectable boundary around an existing Model.
The fastest way to see how the packages compose is to watch several of them
reuse one application declaration. Assume Model, Message, initial, and
update are an ordinary Foldkit todo app you already wrote. Everything around
them derives from the same state machine; none of it introduces a second
reducer.
import { Schema } from 'effect'
import { Agent } from 'foldkit-agent'
import { Mirror } from 'foldkit-mirror'
import { Capability, Slot, Slots, Style } from 'foldkit-mixins'
import { SurfaceView } from 'foldkit-mixins-surface'
import { MessageSet, Module, Projection, Surface } from 'foldkit-surface'
import { DocumentId, Sync } from 'foldkit-sync'
type Principal = { readonly role: 'owner' | 'guest' }
const isOwner = (principal: Principal) => principal.role === 'owner'
// 1. This is still the application: one Model, one Message union, one update.
// Surface adds typed references and inspection metadata; it does not add runtime state.
const App = Surface.application({ Model, Message, initial, update })
// 2. A Surface is a public boundary for a feature: what it may observe and cause.
// A renderer bound to Board can only construct these two Messages.
const Board = App.surface('Board', {
model: ({ model }) => ({ todos: model.todos, filter: model.filter }),
messages: [Message.ToggledTodo, Message.DeletedTodo],
})
// A read-only Surface can be reused by something that only needs context.
const Overview = App.surface('Overview', {
model: ({ model }) => ({ todos: model.todos, filter: model.filter }),
})
// 3. Mixins separate "where customization is allowed" from "what gets attached there."
//
// BoardSlots is the view's public customization contract. It renders nothing by
// itself. It only names the places the view agrees other code may extend later:
// `root` will be the outer <section>; `list` will be the <ul>.
// Capabilities describe what kind of element lives at each point so incompatible
// Styles or Behaviors can be rejected instead of silently doing the wrong thing.
const BoardSlots = Slots.define({
root: Slot.make({ capability: Capability.Container }),
list: Slot.make({ capability: Capability.Collection }),
})
// Style is data written against that slot contract. Nothing is applied yet, and
// BoardStyle cannot read or change application state. Because it is created with
// `forSlots(BoardSlots)`, misspelling a slot or styling one Board never published
// is a type error rather than a convention.
const BoardStyle = Style.forSlots(BoardSlots)({
root: Style.class('todo-board'), // contribute a class to the `root` slot
list: Style.inline({ margin: '0', padding: '0', listStyle: 'none' }), // style `list`
})
// SurfaceView.define ties three boundaries together:
// Board -> the projected Model this view receives and the Messages it may emit
// BoardSlots -> the places outside customization may attach
// render fn -> the actual markup
//
// So `model` is not the whole application Model; it is Board's { todos, filter }.
// And `h` is typed to the Messages Board declared above.
export const BoardView = SurfaceView.define(Board, BoardSlots, (model, slots, h) =>
h.section(
// `.attrs()` is the handoff point between markup and Mixins. It resolves the
// view's own attributes plus every Style/Behavior attached to `root` into
// ordinary Foldkit attributes for this <section>.
slots.root.attrs(),
[
h.ul(
// Same idea here: this exact DOM position is the published `list` slot.
slots.list.attrs(),
model.todos.map(todo => h.li([], [todo.title])),
),
],
),
).pipe(
// Attach appearance from the outside. BoardView never imports CSS decisions into
// its markup, so styles can be swapped/composed without copying the component or
// adding a growing collection of styling props.
Style.attach(BoardStyle),
)
// Behavior can attach element-level interaction through those same slots. It may
// contribute attributes, event handlers, or a Mount, but it still owns no Model;
// application state and transitions remain Model / Message / update.
// 4. Sync declares ownership of one writable slice and the facts that change it.
// Projection.pick is writable because checkpoints must install back into Model;
// replay still runs these Messages through the application's own update.
const TodoSync = Sync.forApplication(App)
.withPrincipal<Principal>()
.make({
documentId: DocumentId.make('todos'),
shared: Projection.pick(App.model.todos),
durable: MessageSet.make(App, [
Message.SubmittedTodo,
Message.ToggledTodo,
Message.DeletedTodo,
]),
authorize: {
// Policy lives on the contract and is enforced by the server journal.
DeletedTodo: ({ principal }) => isOwner(principal),
},
})
// The server gets codecs, empty snapshot, replay, and authorization from Sync.
// There is no second server-side reducer to keep in agreement.
TodoSync.journalContract()
// 5. First specialize the Agent API to this application and Principal type.
// `forApplication(...).withPrincipal(...)` does NOT create an agent; it creates
// a typed builder whose helpers know App's Model, Message union, and Principal.
const AgentBuilder = Agent.forApplication(App).withPrincipal<Principal>()
// `make` creates the concrete agent contract that MCP/WebMCP/A2A/etc. can serve:
// what this agent sees, which existing Messages it may cause, and their policy.
const AssistantAgent = AgentBuilder.make({
context: Overview,
messages: AgentBuilder.expose(Message, {
RequestedTodo: Agent.variant({
name: 'add_todo',
description: 'Add a todo with the given title',
// The protocol input can be smaller than the internal Message. The call's
// invocation id rides on the intent, and the Command copies it onto the fact.
input: Schema.Struct({ title: Schema.String }),
toMessage: ({ title }, { invocation }) => ({ title, requestId: invocation.id }),
// RequestedTodo is an intent. The tool call completes when update later
// applies the durable fact that carries this call's id: two calls adding
// "Milk" each finish on their own todo, which a title could not tell apart.
completion: {
success: Message.SubmittedTodo,
correlate: (_, result, { invocation }) => result.requestId === invocation.id,
},
}),
ToggledTodo: { name: 'toggle_todo', description: 'Toggle a todo' },
DeletedTodo: {
name: 'delete_todo',
description: 'Delete a todo (owner only)',
// Same rule, checked early at the agent boundary; the journal still owns trust.
authorize: ({ principal }) => isOwner(principal),
},
}),
})
// 6. Mirrors do not own state. They are secondary representations of Model fields.
const Filters = Mirror.url(App, {
name: 'filters',
fields: [App.model.filter], // linkable: ?filter=active
})
const Prefs = Mirror.kv(App, {
key: 'todo/prefs',
fields: [App.model.draft], // remembered on this device
})
// 7. The architecture itself is data. Validate ownership/capability relationships,
// or turn the same declarations into documentation and tooling input.
const Project = Module.make(App, [
Board,
Overview,
TodoSync,
AssistantAgent,
Filters.contract,
Prefs.contract,
])
Module.validate(Project) // []
Module.toMermaid(Project) // architecture generated from the declarations above
The code is large because the point is composition, not because any one package requires all of it.
- The application stays the center. Model, Message,
update, Commands, Submodels, and Mounts still mean what they mean in Foldkit. - Surface makes boundaries explicit. A Projection says what a consumer may observe; a Message subset says what it may cause. Those declarations are data, so other packages can reuse and inspect them.
- Extensions reuse application semantics instead of copying them. Agents expose existing Messages, Sync replays them, Mirror represents Model fields elsewhere, and Mixins extends views without owning state.
- Ownership stays singular. A URL mirror does not become a URL store; a replica does not grow a second reducer; a Style does not become view state.
- The architecture itself becomes inspectable.
Module.validatecatches conflicting ownership, andModule.toMermaidturns the declarations into documentation or tooling input.
State changes take exactly two paths, and they are not equal. Ordinary
application transitions travel Message → update. Everything else, such as
a Sync checkpoint, a Mirror restoration or a Remote cache write, installs an
already-derived value through a structural seam (ModelRef.set/modify,
WritableProjection.set). A setter is infrastructure, not a second update;
see Who changes application state, and how.
The important part is what is missing: no agent reducer, sync reducer, URL store, persistence state machine, server copy of the shared schema, or forked component just to restyle it.
foldkit-remote is deliberately not in this block. Remote is easiest to
understand with an actual server-owned entity and query; see
the Remote example or the
kitchen-sink for that path. For the running
version of this app, follow the todo app.
The sample above is typechecked in
examples/todo-app/test/readme.test-d.ts,
so the front page cannot quietly drift from the API.
Which package do I need?
If a term below is new, the glossary defines each one in a line.
| You want to… | Reach for | Read |
|---|---|---|
| Let an LLM or another agent use the app, safely, over MCP, WebMCP, A2A, or Agent Native | foldkit-agent + one adapter |
Agents |
| Cache server entities once, know what is missing, mutate optimistically, keep a write across a reload until the server has it, get live updates | foldkit-remote (+ -server, -drizzle on the server) |
Server-derived state |
| Work offline, on several devices, or with other people, and converge | foldkit-sync on the client, foldkit-durable on the server |
Replicated state |
| Edit rows a server owns offline, with the table kept as the journal's read model | foldkit-sync/entity and foldkit-sync/journal, over foldkit-remote |
Editing server data |
| Keep the filter and page in the URL, remember a draft or a preference | foldkit-mirror |
Mirrored state |
| Declare where the application is: route nodes, typed targets, titles, history intent | foldkit-site (early) |
package README |
| Package a Submodel once and place it several times, or once per key, with every part wired | foldkit-bundle (+ -surface for Module ownership) |
package README |
| Reach for everyday browser primitives instead of hand-wiring them: media queries, timers, sockets, device state, observers, clipboard, one in-browser server for every tab | foldkit-primitives |
package README |
Draw responsive images (srcset, sizes, a source per format, a placeholder, the box held before the file arrives), make and keep their variants on a server or in a build, and import icons as data by name |
foldkit-media (+ Image and Icon.view in foldkit-mixins-ui; early) |
package README |
Restyle or add behaviour to views, including @foldkit/ui, without copying markup |
foldkit-mixins (+ -surface, -ui) |
View composition |
| Use a React component in a Foldkit view, or embed a Foldkit program in a React app | foldkit-react |
package README |
| Compile Foldkit views to React TSX source | foldkit-react-codegen |
package README |
| Say what a feature observes and may cause, and check that nothing owns a field twice | foldkit-surface |
package README |
| Declare a domain once (fields, relations, selections) for the client cache, the database binding, and forms to share | foldkit-entity |
One domain declaration |
| Say once who may read and write what, and have every read, write, Sync edit and agent capability enforce it | foldkit-guard |
package README |
| Build a form from the input an operation accepts, with validation and a decoded value handed to the parent | foldkit-form (+ foldkit-mixins-form to draw it) |
package README |
| Join a form, a Remote mutation or query, and their Entity into an edit screen or a list | foldkit-crud (+ foldkit-mixins-crud to draw lists and details) |
package README |
| Edit an interactive grid over rows the application owns: keyboard focus, ranges, typed editors, copy and paste, fill, 100,000 rows virtualized | foldkit-data-grid (+ foldkit-mixins-data-grid to draw it; experimental) |
package README |
Render on the server and hand the Model over, rather than rerunning init: resumable pages, forms without scripts |
foldkit-ssr |
package README |
One server fetch from parts: assets, the configured origin, routes in order, values built once per isolate, the page template, the same handler on Node |
foldkit-host (early) |
package README |
| Give content drafts, revisions, a schedule, and a published/unpublished boundary, without a status column | foldkit-cms + foldkit-cms-drizzle (the editor's state and the server) |
package README |
| Edit rich text: a semantic document in the Model, an editor on the page, Markdown in and out | foldkit-richtext + foldkit-richtext-dom (+ -markdown, -code or -code-shiki for highlighted code, and foldkit-mixins-richtext to draw the chrome) |
package README |
| Store a page as Blocks in Regions, checked against a Catalog of what may exist | foldkit-composition (experimental) |
package README |
| Edit such a page with a selection and undo, as one key of a form | foldkit-builder (+ foldkit-mixins-builder to draw it; experimental) |
package README |
foldkit-surface is the shared semantic seam for Agent, Remote, Sync, Mirror,
and the Surface/Mixins bridge. It is not a mandatory base class for the whole
repository: foldkit-durable, core foldkit-mixins, and the protocol/UI
adapters can stand on their own and meet Surface-backed packages at explicit
boundaries.
foldkit-plus MCP questions
How do I add foldkit-plus MCP to Claude Code?
Run claude mcp add foldkit-plus -- npx -y foldkit-agent in your terminal. Add --scope user to make it available in every project.
How do I add foldkit-plus MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.