dci-mcp 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# dci-mcp
+
+An MCP server that generates code adhering to the [DCI architecture](https://en.wikipedia.org/wiki/Data,_context_and_interaction) when generating or refactoring code. It loads language-specific rules and examples, then instructs the LLM to apply them immediately — no back-and-forth.
+
+## Tools
+
+| Tool                             | When to use                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `prepare_dci_refactor`           | User wants to refactor existing code into DCI                              |
+| `scaffold_dci_from_mental_model` | User describes a mental model / user story and wants DCI code from scratch |
+
+Both tools accept a `language` argument (e.g. `"typescript"`, `"javascript"`) and return the full DCI ruleset for that language as context.
+
+## Supported languages
+
+Add a folder under `docs/` with `instructions.md` (required) and `examples.md` (optional):
+
+```
+docs/
+  core.md              # DCI rules shared across all languages
+  typescript/
+    instructions.md
+    examples.md
+  javascript/
+    instructions.md
+    examples.md
+```
+
+## Usage in mcp.json (stdio)
+
+```jsonc
+"dci": {
+  "command": "pnpx",
+  "args": ["dci-mcp"]
+}
+```
+
+Or with npx:
+
+```jsonc
+"dci": {
+  "command": "npx",
+  "args": ["-y", "dci-mcp"]
+}
+```
+
+## Development
+
+```sh
+pnpm install
+pnpm dev          # build + pnpm link (makes dci-mcp available globally)
+pnpm inspector    # open MCP Inspector connected to the local server
+```
+
+After `pnpm dev`, the server is available as `dci-mcp` in your PATH and can be used in `mcp.json` outside this project while you iterate:
+
+```jsonc
+"dci": {
+  "command": "dci-mcp"
+}
+```

package/dist/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+const { version } = createRequire(import.meta.url)("../package.json");
+// Register the Tools
+const languageSchema = z.object({
+    language: z
+        .string()
+        .describe("The target programming language, matching a folder name under docs/ (e.g. 'typescript', 'javascript')"),
+});
+// Initialize the MCP Server
+const server = new McpServer({
+    name: "dci-mcp",
+    version,
+});
+// Calculate paths to the docs directory
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = path.join(__dirname, "..", "docs");
+/**
+ * Helper function to read, concatenate, and append action-specific directives.
+ */
+async function getDciInstructions(language, action) {
+    const corePath = path.join(DOCS_DIR, "core.md");
+    const langPath = path.join(DOCS_DIR, language, "instructions.md");
+    const examplesPath = path.join(DOCS_DIR, language, "examples.md");
+    try {
+        // Read core and language instructions concurrently; examples are optional
+        const [coreContent, langContent] = await Promise.all([
+            fs.readFile(corePath, "utf-8"),
+            fs.readFile(langPath, "utf-8"),
+        ]);
+        let examplesContent = "";
+        try {
+            examplesContent = await fs.readFile(examplesPath, "utf-8");
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        let response = `${coreContent}\n\n${langContent}`;
+        if (examplesContent) {
+            response += `\n\n${examplesContent}`;
+        }
+        response += "\n\n";
+        // Append the action-specific LLM directive
+        if (action === "refactor") {
+            response += `
+---
+**CRITICAL INSTRUCTION FOR YOUR NEXT RESPONSE:**
+You now have the strict DCI rules. Do not ask for confirmation. Immediately analyze the user's legacy code, silently plan the Data/Roles/Context, and generate the refactored DCI code in your next response.
+`;
+        }
+        else if (action === "scaffold") {
+            response += `
+---
+**CRITICAL INSTRUCTION FOR YOUR NEXT RESPONSE:**
+You now have the strict DCI rules. Do not ask for confirmation. Read the user's mental model/user story from the chat history and immediately translate it into a DCI Context. 
+
+As you generate the code, ensure:
+1. **Roles map to the actors/concepts** in their mental model.
+2. **RoleMethods express the exact steps** described in their story.
+3. You strictly separate the dumb Data ("what the system is") from the Context ("what the system does").
+`;
+        }
+        return response;
+    }
+    catch (error) {
+        throw new Error(`Failed to load DCI instructions for '${language}'. Ensure the language folder exists in the docs/ directory. Error details: ${error.message}`);
+    }
+}
+server.registerTool("prepare_dci_refactor", {
+    title: "Prepare DCI Refactor",
+    description: "Call this tool when the user asks to refactor code into the DCI paradigm. Pass the target language. The tool will return the strict DCI architectural rules you need to follow before generating the final code.",
+    inputSchema: languageSchema,
+}, async ({ language }) => {
+    try {
+        const content = await getDciInstructions(language.toLowerCase(), "refactor");
+        return { content: [{ type: "text", text: content }] };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error executing tool: ${error.message}. Please inform the user that this language might not be supported in the DCI server yet.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+server.registerTool("scaffold_dci_from_mental_model", {
+    title: "Scaffold DCI from Mental Model",
+    description: "Call this tool when the user provides a mental model or user story and wants you to write a new DCI Context from scratch. The tool will return the strict DCI architectural rules required to translate their mental model into code.",
+    inputSchema: languageSchema,
+}, async ({ language }) => {
+    try {
+        const content = await getDciInstructions(language.toLowerCase(), "scaffold");
+        return { content: [{ type: "text", text: content }] };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error executing tool: ${error.message}. Please inform the user that this language might not be supported in the DCI server yet.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server using stdio transport
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("DCI Architect MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/docs/core.md

@@ -0,0 +1,156 @@
+# Instructions for Writing Code with the DCI Paradigm
+
+> **DCI: Data, Context and Interaction:**
+> DCI is a programming paradigm that separates _what the system is_ (domain knowledge/data models) from _what the system does_ (behavior/functionality), bridging human mental models and code.
+
+## 1. Core DCI Architecture
+
+- DCI code is organized around three projections:
+
+### Data ("What the system _is_")
+
+- Domain objects, with simple properties and methods that only regards its own data.
+- Pure data structures that represent the state of the system.
+- Classes or types that do NOT contain interaction logic relevant to the current use case.
+
+### Context ("What the system _does_")
+
+- Encapsulates a _use case_ based on a mental model.
+- Orchestrates interactions between Data objects by assigning them **Roles** at runtime.
+- The (public) properties of these Data objects form the **Role Contracts**, a partial interface for accessing the role-playing object by its Role.
+- A Context encapsulates one complete use case or user story, with all variations expressed in the Context.
+
+### Interaction ("How the system does it")
+
+- Specifies _how_ objects collaborate inside a Context - via **RoleMethods**.
+- RoleMethods define the behavior of objects playing specific Roles.
+- IMPORTANT: ONLY the Role's own RoleMethods can access its Role Contract (the underlying object properties) directly. There CAN NOT be any access to the Role Contract from outside the RoleMethods of that Role, not even from other RoleMethods of other Roles. The only way to access the Role Contract from other Roles is through RoleMethod calls.
+- Internal (private) RoleMethods are callable _only_ by RoleMethods in the same Role.
+- Interactions should favor "ask, don't tell" (objects request services, not micromanage).
+- The starting point for a Role interaction (a flow of messages through the Context) is called a **System Operation**.
+- In a true DCI runtime, RoleMethods are attached _dynamically_ to the objects playing the Roles, and only exist during Context execution, but this is language- and implementation-specific.
+
+## 2. DCI Principles & Key Concepts
+
+### Mental Model Alignment
+
+- DCI code should map closely to how users think about the domain.
+- The RoleMethods should express what the user wants the role-playing objects to do, based on their properties.
+
+### Roles
+
+- Role = An identifier for an object in a Context; not a reusable type.
+- Objects can play a Role if they fulfill the Role's contract (literal type).
+- Roles are _not wrappers_; object identity MUST be preserved.
+
+### Object Identity
+
+- Real objects, not proxies or wrappers, play Roles to maintain their identity.
+
+### Separation of Concerns
+
+- Domain knowledge (Data) evolves slowly; use case logic (Context/Interaction) changes rapidly.
+- Keep these separate for maintainability.
+
+### Readability
+
+- Gather use case logic in one place (the Context).
+- Use comments and types to clarify contracts and intent.
+
+### Runtime Focus
+
+- DCI describes system behavior _at runtime_, not just compile-time structure.
+
+### Agile Support
+
+- DCI supports practices like iterative development, clear mental models, and adaptation to change.
+
+### When not to use DCI
+
+- DCI is best suited for use cases where there are two or more interacting actors.
+- For simple operations like CRUD, or purely functional data transformation, do not use DCI.
+- If a use case tends to contain only one Role or be specific enough not to express a genericity of its Role interfaces, do not use DCI.
+
+## 3. DCI Analogies
+
+### Movie Script
+
+- The Context is the script; objects are actors; Roles are character parts.
+- Objects (actors) can play different Roles in different Contexts (scenes).
+
+### Train System
+
+- Instead of modeling trains or stations individually, DCI models their patterns of interaction (e.g., station visits).
+
+### Automated factory
+
+- When producing different products, the factory (Context) assigns machines (objects) to different Roles based on the product being made.
+- The product is passed between the machines (through Role Method arguments), each using its Role Contract to modify or use it, until the goal of the Context has been achieved.
+
+### Extending the Context
+
+- Extending the Context (adding variations to the use case) should be like rewiring cables (RoleMethod calls), not changing domain objects. The simple data playing the Context Roles should be able to play a part in many different scenarios through their interfaces.
+
+## 4. DCI Code Generation Workflow
+
+1. **Start with the Use Case**
+
+- What does the user want to _achieve_?
+- Define this as a Context.
+- If a mental model or use case is supplied, use it as a foundation for the Roles and RoleMethods.
+- Do NOT name the context "SubmitContext" or similar, but rather after the use case (e.g., `SubmitForm`, `LibraryMachine`).
+
+2. **Identify Roles**
+
+- What objects collaborate for this use case?
+- Roles must be located _inside_ the Context.
+- Roles should be played by _objects_, not primitive types. Primitive types passed to the Context, like configuration options, can be expressed as a settings object, played by a `Context` role.
+- Additional Context state, usually transient, can also be added as properties to the `Context` role if few and simple, otherwise a separate Role can be created for it, usually when a Context needs to construct an object throughout its Interaction, like a `Response` to a HTTP request.
+- Name the Roles meaningfully (e.g., `SourceAccount`, `Messages`), do NOT append `Role` to the name.
+- DON'T add Roles that are not relevant to the use case/mental model, or just for technical reasons (e.g., a `Database` Role for database access, `ResponseComposer` for constructing a HTTP response, or roles that act like software design patterns). Instead, consider whether the technical dependency can be abstracted behind a Role Contract of an existing Role, or if it is truly needed as a separate Role.
+
+3. **Define Role Contracts**
+
+- What properties/methods must an object have for its Role, for the Context goal to be fulfilled?
+- Define clear, minimal contracts that specify the interface needed for each Role.
+- Use the language's type system to express these contracts explicitly.
+
+4. **Implement RoleMethods**
+
+- Write interaction logic _inside_ the Context.
+- Group RoleMethods by Role for clarity.
+- RoleMethods should be kept together. No mixing of RoleMethods or other instructions between RoleMethods belonging to the same role.
+- DON'T add RoleMethods without Roles, that's just helper functions in disguise. RoleMethods MUST have a corresponding Role identifier with a Contract, so they further the Context goal ("doing their part" in the use case) and are not just utility functions, which _can_ exist on a Role but usually as private RoleMethods.
+- Most of the time, RoleMethods should "chain" together the Interaction in progress, meaning that at the end of a RoleMethod, another RoleMethod of a Role is called, passing on relevant data as arguments, further fulfilling the purpose of the Context according to the mental model. This chaining avoids the dependency on return values and makes it easier to "rewire" the context later if requirements change, or new functionality is added.
+- If a RoleMethod is called only once in the Context, it is usually better to inline its logic into the caller RoleMethod to avoid unnecessary indirection. But if it is called multiple times, or if it is a distinct step in the use case that can be clearly named, it can be a separate RoleMethod (if it can be connected to a relevant Role).
+
+5. **Focus on Interaction**
+
+- RoleMethods should coordinate with other Roles ("ask"), not dictate ("tell").
+- When data is acquired or created within a RoleMethod, for example through a Role Contract method call, if needed by other Roles it should be passed to other RoleMethods, expressing the interaction and collaboration of the Roles - true object-orientation.
+- Return values should be avoided if possible (think message-passing that ultimately modifies state), but is not prohibited, for example an occasional boolean check. Readability is the goal, not enforcing rules that complicates the code.
+
+6. **Keep Data Pure**
+
+- Domain objects (classes/types) must NOT contain Context-specific logic.
+
+7. **Preserve Object Identity**
+
+- Role wrappers can lead to subtle bugs with strict equality checks, so NEVER wrap objects for Role assignment - always use direct references.
+
+8. **Role-binding**
+
+- All Roles _must_ be bound (assigned) either during the Context initialization, or in a single `rebind` function that reassigns _all_ Roles.
+- If one or more Roles must change during the Context execution, prefer reinstantiating the Context again, or use the `rebind` function to avoid recursion for example.
+- Roles _can_ be bound to null, but is unusual and a good reason must exist for that.
+
+9. **Nested Contexts**
+
+- If a RoleMethod's logic represents a _reusable_, _distinct_ use case, consider implementing it as a separate Context. This keeps Contexts focused and manageable.
+- Calling such a Context within another is called "nesting" Contexts.
+- Follow the rules about when not to use DCI to determine whether to use nested Contexts.
+
+10. **Documentation**
+
+- Document Contexts clearly with their purpose and use case.
+- Clarify Role Contracts with appropriate type annotations or comments.

package/docs/javascript/examples.md

@@ -0,0 +1,437 @@
+## JavaScript DCI Examples
+
+### AJAX form submit with dynamic error display
+
+- Notable as a "one off" operation, nothing is returned from the Context function.
+- Also demonstrates the basics of Context error handling by using a single try/catch around the System Operation part, to avoid errors leaking outside the RoleMethods.
+
+```js
+/**
+ * Submit a form and show error messages from the response.
+ * @DCI-context
+ * @param {SubmitEvent} e
+ */
+async function SubmitForm(e) {
+  if (!(e.target instanceof HTMLFormElement)) throw new Error("No form found.");
+
+  //#region Form Role ////////////////////
+
+  /** @type {{ action: string }} */
+  const Form = e.target;
+
+  async function Form_submit() {
+    // Role contract: Form.action
+    const response = await fetch(Form.action, {
+      method: "POST",
+      body: new FormData(Form),
+    });
+    const data = await response.json();
+    for (const error of data.errors ?? []) Messages_show(error); // Role interaction
+  }
+
+  //#endregion
+
+  //#region Messages Role ////////////////////
+
+  const Messages = e.target.querySelectorAll("[data-form-message]");
+
+  async function Messages_hide() {
+    Messages__set("none");
+    await Form_submit(); // Role interaction
+  }
+
+  /** @param {string} name */
+  function Messages_show(name) {
+    Messages__set("unset", name);
+  }
+
+  /**
+   * @param {string} display
+   * @param {string} [name]
+   */
+  function Messages__set(display, name = "") {
+    for (const msg of Messages) {
+      if (name && msg.dataset.formMessage != name) continue;
+      msg.style.display = display;
+    }
+  }
+
+  //#endregion
+
+  try {
+    console.log("Submit");
+    e.preventDefault();
+    await Messages_hide(); // System operation
+    console.log("Done");
+  } catch (e) {
+    console.error(e);
+  }
+}
+```
+
+### Session validation for SvelteKit and Drizzle
+
+- Another "one off" operation, where ultimately the Request is modified to have valid or invalid session data.
+- The Roles are defined in the _Context arguments_, so they will not have their common place before their RoleMethods, which they would if they were defined inside the Context.
+- The System Operation (initial RoleMethod call) is started right away, as all Roles are defined in the Context arguments.
+
+```js
+/**
+ * Sets locals.user and locals.session on success, otherwise null.
+ * @DCI-context
+ * @param {import('@sveltejs/kit').RequestEvent} Request
+ * @param {typeof db} [Session]
+ * @param {boolean} [INVALIDATE]
+ * @returns {Promise<void>}
+ */
+export async function ValidateSession(
+  Request,
+  Session = db,
+  INVALIDATE = false,
+) {
+  await Request_getTokenFromCookie();
+
+  //#region Request //////////////////////////////
+
+  async function Request_getTokenFromCookie() {
+    const token = Request.cookies.get(COOKIE_NAME);
+
+    if (!token) Request_clearSession();
+    else await Session_findByToken(token);
+  }
+
+  /**
+   * @param {string} token
+   * @param {import('$lib/db').Session} session
+   * @param {import('$lib/db').User} user
+   */
+  function Request_setSession(token, session, user) {
+    Object.freeze(user);
+    Object.freeze(session);
+
+    Request.cookies.set(COOKIE_NAME, token, {
+      httpOnly: true,
+      sameSite: "lax",
+      expires: session.expiresAt,
+      path: "/",
+    });
+
+    Request.locals.user = user;
+    Request.locals.session = session;
+  }
+
+  function Request_clearSession() {
+    Request.cookies.set(COOKIE_NAME, "", {
+      httpOnly: true,
+      sameSite: "lax",
+      maxAge: 0,
+      path: "/",
+    });
+
+    Request.locals.user = undefined;
+    Request.locals.session = undefined;
+  }
+
+  //#region Session ////////////////////////////////////////
+
+  /** @param {string} token */
+  async function Session_findByToken(token) {
+    const sessionId = encodeHexLowerCase(
+      sha256(new TextEncoder().encode(token)),
+    );
+
+    const [result] = await Session.select({
+      user: userTable,
+      session: sessionTable,
+    })
+      .from(sessionTable)
+      .innerJoin(userTable, eq(sessionTable.userId, userTable.id))
+      .where(eq(sessionTable.id, sessionId))
+      .limit(1);
+
+    if (!result) Request_clearSession();
+    else await Session_checkExpiryDate(token, result.session, result.user);
+  }
+
+  /**
+   * @param {string} token
+   * @param {import('$lib/db').Session} session
+   * @param {import('$lib/db').User} user
+   */
+  async function Session_checkExpiryDate(token, session, user) {
+    if (INVALIDATE || Date.now() >= session.expiresAt.getTime()) {
+      await Session.delete(sessionTable).where(eq(sessionTable.id, session.id));
+      Request_clearSession();
+    } else {
+      await Session_refreshExpiryDate(token, session, user);
+    }
+  }
+
+  /**
+   * @param {string} token
+   * @param {import('$lib/db').Session} session
+   * @param {import('$lib/db').User} user
+   */
+  async function Session_refreshExpiryDate(token, session, user) {
+    if (
+      Date.now() >=
+      session.expiresAt.getTime() - 1000 * 60 * 60 * 24 * (EXPIRY_DAYS / 2)
+    ) {
+      session.expiresAt = new Date(
+        Date.now() + 1000 * 60 * 60 * 24 * EXPIRY_DAYS,
+      );
+      await Session.update(sessionTable)
+        .set({
+          expiresAt: session.expiresAt,
+        })
+        .where(eq(sessionTable.id, session.id));
+    }
+
+    Request_setSession(token, session, user);
+  }
+}
+```
+
+### A book borrowing machine at a public library
+
+- Notable as it returns an object from the Context, similar to a class with public methods.
+- The `Screen` and `Printer` Roles are defined in the _Context arguments_, so they will not have their common place before their RoleMethods, which they would if they were defined inside the Context, as the other Roles are.
+
+```js
+import { Display } from "$lib/assets/screen/screenStates";
+import { title } from "$lib/data/libraryItem";
+import { cards, library, loans } from "$lib/library";
+import { hash } from "$lib/utils";
+import { BorrowItem } from "./borrowItem";
+
+/**
+ * A book borrowing machine at a public library.
+ * @DCI-context
+ * @param {{ display: (state: object) => void, currentState: () => object }} Screen
+ * @param {{ print: (line: string) => void }} Printer
+ */
+export function LibraryMachine(Screen, Printer) {
+  //#region Borrower /////
+
+  /** @type {{ "@id": string, "@type": "Person", items: { id: string, title: string, expires: Date }[] }} */
+  let Borrower;
+
+  function Borrower_isLoggedIn() {
+    // A getter is ok if it is descriptive beyond "get" and returns a boolean
+    return !!Borrower["@id"];
+  }
+
+  /** @param {{ "@id": string, "@type": string }} user */
+  function Borrower_login(user) {
+    rebind(user["@id"]);
+    Screen_displayItems(Borrower.items);
+  }
+
+  /**
+   * @param {boolean} forced Whether the logout was forced by the user (e.g. card removed)
+   * @param {boolean} printItems
+   */
+  function Borrower_logout(forced, printItems) {
+    // Need to print before rebinding, as it will clear the items
+    if (printItems) Printer_printReceipt(Borrower.items);
+
+    if (Borrower_isLoggedIn()) rebind(undefined);
+    Screen_displayThankYou(forced);
+  }
+
+  /** @param {string | undefined} itemId */
+  function Borrower_borrowItem(itemId) {
+    // TODO: Built-in security (assertions) for required login
+    if (!Borrower_isLoggedIn() || !itemId) return;
+
+    if (Borrower.items.find((item) => item.id === itemId)) return;
+
+    // Call nested context
+    const loan = BorrowItem(library, Borrower, { "@id": itemId }, loans);
+
+    // TODO: Error handling (logging) for expected errors
+    if (loan instanceof Error) return Screen_displayError(loan);
+
+    Borrower.items.push({
+      id: loan.object["@id"],
+      title: title(loan.object),
+      expires: loan.endTime,
+    });
+
+    Screen_displayItems(Borrower.items);
+  }
+
+  //#endregion
+
+  //#region CardReader /////
+
+  const CardReader = {
+    currentId: "",
+    attempts: 0,
+  };
+
+  /** @param {string | undefined} id */
+  function CardReader_cardScanned(id) {
+    if (CardReader.currentId == id) return;
+
+    if (!id) {
+      // Card removed or missing
+      if (CardReader.currentId) Borrower_logout(true, false);
+    } else {
+      // Card scanned
+      if (!Borrower_isLoggedIn()) {
+        // New card
+        Screen_displayEnterPIN(0);
+      }
+    }
+
+    CardReader.currentId = id ?? "";
+  }
+
+  function CardReader_resetAttempts() {
+    CardReader.attempts = 0;
+  }
+
+  /** @param {string[]} pin */
+  function CardReader_validatePIN(pin) {
+    Library_validateCard(CardReader.currentId, pin);
+  }
+
+  function CardReader_PINfailed() {
+    // TODO: Force remove card after 3 failed attempts
+    Screen_displayEnterPIN(++CardReader.attempts);
+  }
+
+  //#endregion
+
+  //#region Library /////
+
+  const Library = {
+    cards,
+  };
+
+  /**
+   * @param {string} cardId
+   * @param {string[]} pin
+   */
+  function Library_validateCard(cardId, pin) {
+    const card = Library.cards.find((card) => card["@id"] === cardId);
+    if (card && card.identifier === hash(pin.join(""))) {
+      Borrower_login(card._owner);
+    } else {
+      CardReader_PINfailed();
+    }
+  }
+
+  //#endregion
+
+  //#region Screen /////
+
+  function Screen_displayWelcome() {
+    Screen.display({ display: Display.Welcome });
+  }
+
+  /** @param {number} attempts */
+  function Screen_displayEnterPIN(attempts) {
+    Screen.display({ display: Display.EnterPIN, attempts });
+  }
+
+  /** @param {{ title: string, expires: Date }[]} items */
+  function Screen_displayItems(items) {
+    Screen.display({ display: Display.Items, items });
+  }
+
+  /** @param {boolean} forced */
+  function Screen_displayThankYou(forced) {
+    if (forced && Screen.currentState().display === Display.ThankYou) {
+      Screen_displayWelcome();
+    } else {
+      Screen.display({ display: Display.ThankYou });
+      if (forced) Screen__displayNext({ display: Display.Welcome });
+    }
+  }
+
+  /** @param {Error} error */
+  function Screen_displayError(error) {
+    // Log out user
+    rebind(undefined);
+    Screen.display({ display: Display.Error, error });
+    Screen__displayNext({ display: Display.Welcome }, 10000);
+  }
+
+  /**
+   * @param {object} nextState
+   * @param {number} [delay]
+   */
+  function Screen__displayNext(nextState, delay = 5000) {
+    const currentState = Screen.currentState();
+    setTimeout(() => {
+      if (currentState === Screen.currentState()) Screen.display(nextState);
+    }, delay);
+  }
+
+  //#endregion
+
+  //#region Printer /////
+
+  /** @param {{ title: string, expires: Date }[]} items */
+  async function Printer_printReceipt(items) {
+    if (items.length) {
+      await Printer__printLine(new Date().toISOString().slice(0, 10));
+      await Printer__printLine("");
+      for (const item of items) {
+        await Printer__printLine(item.title);
+        await Printer__printLine(
+          "Return on " + item.expires.toISOString().slice(0, 10),
+        );
+        await Printer__printLine("");
+      }
+    }
+  }
+
+  /** @param {string} line */
+  async function Printer__printLine(line) {
+    Printer.print(line);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  //#endregion
+
+  /**
+   * Reset the Context state, rebind to a new user or undefined (not logged in).
+   * @param {string | undefined} userId
+   */
+  function rebind(userId) {
+    Borrower = { "@id": userId ?? "", "@type": "Person", items: [] };
+    CardReader_resetAttempts();
+  }
+
+  {
+    // Context start
+    rebind(undefined);
+    Screen_displayWelcome();
+
+    return {
+      /** @param {string | undefined} id */
+      cardScanned(id) {
+        CardReader_cardScanned(id);
+      },
+
+      /** @param {string | undefined} id */
+      itemScanned(id) {
+        Borrower_borrowItem(id);
+      },
+
+      /** @param {string[]} pin */
+      pinEntered(pin) {
+        CardReader_validatePIN(pin);
+      },
+
+      /** @param {boolean} printReceipt */
+      finish(printReceipt) {
+        Borrower_logout(false, printReceipt);
+      },
+    };
+  }
+}
+```

package/docs/javascript/instructions.md

@@ -0,0 +1,61 @@
+## JavaScript-Specific Implementation
+
+### Context Implementation
+
+- A Context is a function annotated with `@DCI-context`. If that doesn't exist, _do not_ apply DCI.
+- Contexts and their RoleMethods can be async functions when needed.
+
+### Role Contracts
+
+- Use literal types in JSDoc as Role Contracts, so the code can be understood without deeper type knowledge. Example:
+
+```js
+/** @type {{ action: string }} */
+const Form = event.target;
+```
+
+- EXCEPTION: If the types are well-known, like the JavaScript Web APIs, you can reference them directly (e.g., `Page`, `HTMLElement`). Example:
+
+```js
+/** @type {Page} */
+const Page = await Browser.newPage();
+```
+
+- If an object is passed to the Context function that fits the mental model of a Context Role, the Role should be defined from it with the Role Contract as the parameter type. This is the ONLY case RoleMethods should exist in the Context without their Role defined immediately before them. Example:
+
+```js
+/**
+ * @DCI-context
+ * A speaker proclaims something to the world, that dutifully notes it
+ */
+function HelloWorld(
+  /** @type {{ phrase: string }} */ Speaker,
+  /** @type {{ log: (msg: unknown) => void }} */ World,
+) {
+  function Speaker_proclaim() {
+    World_note(Speaker.phrase);
+  }
+
+  function World_note(phrase) {
+    World.log(phrase);
+  }
+
+  Speaker_proclaim();
+}
+```
+
+### RoleMethod Naming
+
+- RoleMethods are functions within the Context scope, named `Role_method()`. Example: `Speaker_proclaim()`, `World_note()`
+- Internal (private) RoleMethods, callable only by RoleMethods in the same Role, use a double underscore: `Role__method()`.
+
+### Role Organization
+
+- Use `//#region RoleName Role /////` and `//#endregion` comments to group RoleMethods by Role. This enables easy folding/unfolding of Roles in the editor.
+
+### Type Annotations
+
+- Use JSDoc for typing, and `@ts-check` on top if creating a new file.
+- Use `@DCI-context` tag to mark Context functions.
+- Clarify Role Contracts with explicit types inline.
+- Prefer inline literal types over separate type declarations for Role Contracts.

package/docs/typescript/examples.md

@@ -0,0 +1,409 @@
+## TypeScript DCI Examples
+
+### AJAX form submit with dynamic error display
+
+- Notable as a "one off" operation, nothing is returned from the Context function.
+- Also demonstrates the basics of Context error handling by using a single try/catch around the System Operation part, to avoid errors leaking outside the RoleMethods.
+
+```ts
+/**
+ * Submit a form and show error messages from the response.
+ * @DCI-context
+ */
+async function SubmitForm(e: SubmitEvent) {
+  if (!(e.target instanceof HTMLFormElement)) throw new Error("No form found.");
+
+  //#region Form Role ////////////////////
+
+  const Form: { action: string } = e.target;
+
+  async function Form_submit() {
+    // Role contract: Form.action
+    const response = await fetch(Form.action, {
+      method: "POST",
+      body: new FormData(Form as HTMLFormElement),
+    });
+    const data = await response.json();
+    for (const error of data.errors ?? []) Messages_show(error); // Role interaction
+  }
+
+  //#endregion
+
+  //#region Messages Role ////////////////////
+
+  const Messages: Iterable<{
+    dataset: DOMStringMap;
+    style: CSSStyleDeclaration;
+  }> = e.target.querySelectorAll<HTMLElement>("[data-form-message]");
+
+  async function Messages_hide() {
+    Messages__set("none");
+    await Form_submit(); // Role interaction
+  }
+
+  function Messages_show(name: string) {
+    Messages__set("unset", name);
+  }
+
+  function Messages__set(display: string, name = "") {
+    for (const msg of Messages) {
+      if (name && msg.dataset.formMessage != name) continue;
+      msg.style.display = display;
+    }
+  }
+
+  //#endregion
+
+  try {
+    console.log("Submit");
+    e.preventDefault();
+    await Messages_hide(); // System operation
+    console.log("Done");
+  } catch (e) {
+    console.error(e);
+  }
+}
+```
+
+### Session validation for SvelteKit and Drizzle
+
+- Another "one off" operation, where ultimately the Request is modified to have valid or invalid session data.
+- The Roles are defined in the *Context arguments*, so they will not have their common place before their RoleMethods, which they would if they were defined inside the Context.
+- The System Operation (initial RoleMethod call) is started right away, as all Roles are defined in the Context arguments.
+
+```ts
+/**
+ * Sets locals.user and locals.session on success, otherwise null.
+ * @DCI-context
+ */
+export async function ValidateSession(
+  Request: RequestEvent,
+  Session = db,
+  INVALIDATE = false
+): Promise<void> {
+  await Request_getTokenFromCookie();
+
+  //#region Request //////////////////////////////
+
+  async function Request_getTokenFromCookie() {
+    const token = Request.cookies.get(COOKIE_NAME);
+
+    if (!token) Request_clearSession();
+    else await Session_findByToken(token);
+  }
+
+  function Request_setSession(token: string, session: Session, user: User) {
+    Object.freeze(user);
+    Object.freeze(session);
+
+    Request.cookies.set(COOKIE_NAME, token, {
+      httpOnly: true,
+      sameSite: "lax",
+      expires: session.expiresAt,
+      path: "/",
+    });
+
+    Request.locals.user = user;
+    Request.locals.session = session;
+  }
+
+  function Request_clearSession(): void {
+    Request.cookies.set(COOKIE_NAME, "", {
+      httpOnly: true,
+      sameSite: "lax",
+      maxAge: 0,
+      path: "/",
+    });
+
+    Request.locals.user = undefined;
+    Request.locals.session = undefined;
+  }
+
+  //#region Session ////////////////////////////////////////
+
+  async function Session_findByToken(token: string) {
+    const sessionId = encodeHexLowerCase(
+      sha256(new TextEncoder().encode(token))
+    );
+
+    const [result] = await Session.select({
+      user: userTable,
+      session: sessionTable,
+    })
+      .from(sessionTable)
+      .innerJoin(userTable, eq(sessionTable.userId, userTable.id))
+      .where(eq(sessionTable.id, sessionId))
+      .limit(1);
+
+    if (!result) Request_clearSession();
+    else await Session_checkExpiryDate(token, result.session, result.user);
+  }
+
+  async function Session_checkExpiryDate(
+    token: string,
+    session: Session,
+    user: User
+  ) {
+    if (INVALIDATE || Date.now() >= session.expiresAt.getTime()) {
+      await Session.delete(sessionTable).where(eq(sessionTable.id, session.id));
+      Request_clearSession();
+    } else {
+      await Session_refreshExpiryDate(token, session, user);
+    }
+  }
+
+  async function Session_refreshExpiryDate(
+    token: string,
+    session: Session,
+    user: User
+  ) {
+    if (
+      Date.now() >=
+      session.expiresAt.getTime() - 1000 * 60 * 60 * 24 * (EXPIRY_DAYS / 2)
+    ) {
+      session.expiresAt = new Date(
+        Date.now() + 1000 * 60 * 60 * 24 * EXPIRY_DAYS
+      );
+      await Session
+        .update(sessionTable)
+        .set({
+          expiresAt: session.expiresAt,
+        })
+        .where(eq(sessionTable.id, session.id));
+    }
+
+    Request_setSession(token, session, user);
+  }
+}
+```
+
+### A book borrowing machine at a public library
+
+- Notable as it returns an object from the Context, similar to a class with public methods.
+- The `Screen` and `Printer` Roles are defined in the *Context arguments*, so they will not have their common place before their RoleMethods, which they would if they were defined inside the Context, as the other Roles are.
+
+```ts
+import { Display, type ScreenState } from "$lib/assets/screen/screenStates";
+import { title } from "$lib/data/libraryItem";
+import { cards, library, loans } from "$lib/library";
+import { hash } from "$lib/utils";
+import { BorrowItem } from "./borrowItem";
+
+/**
+ * A book borrowing machine at a public library.
+ * @DCI-context
+ */
+export function LibraryMachine(
+  Screen: {
+    display: (state: ScreenState) => void;
+    currentState: () => ScreenState;
+  },
+  Printer: {
+    print: (line: string) => void;
+  }
+) {
+  //#region Borrower /////
+
+  let Borrower: {
+    "@id": string;
+    "@type": "Person";
+    items: { id: string; title: string; expires: Date }[];
+  };
+
+  function Borrower_isLoggedIn() {
+    // A getter is ok if it is descriptive beyond "get" and returns a boolean
+    return !!Borrower["@id"];
+  }
+
+  function Borrower_login(user: Pick<typeof Borrower, "@id" | "@type">) {
+    rebind(user["@id"]);
+    Screen_displayItems(Borrower.items);
+  }
+
+  /**
+   * @param forced Whether the logout was forced by the user (e.g. card removed)
+   */
+  function Borrower_logout(forced: boolean, printItems: boolean) {
+    // Need to print before rebinding, as it will clear the items
+    if (printItems) Printer_printReceipt(Borrower.items);
+
+    if (Borrower_isLoggedIn()) rebind(undefined);
+    Screen_displayThankYou(forced);
+  }
+
+  function Borrower_borrowItem(itemId: string | undefined) {
+    // TODO: Built-in security (assertions) for required login
+    if (!Borrower_isLoggedIn() || !itemId) return;
+
+    if (Borrower.items.find((item) => item.id === itemId)) return;
+
+    // Call nested context
+    const loan = BorrowItem(library, Borrower, { "@id": itemId }, loans);
+
+    // TODO: Error handling (logging) for expected errors
+    if (loan instanceof Error) return Screen_displayError(loan);
+
+    Borrower.items.push({
+      id: loan.object["@id"],
+      title: title(loan.object),
+      expires: loan.endTime,
+    });
+
+    Screen_displayItems(Borrower.items);
+  }
+
+  //#endregion
+
+  //#region CardReader /////
+
+  const CardReader: { currentId: string; attempts: number } = {
+    currentId: "",
+    attempts: 0,
+  };
+
+  function CardReader_cardScanned(id: string | undefined) {
+    if (CardReader.currentId == id) return;
+
+    if (!id) {
+      // Card removed or missing
+      if (CardReader.currentId) Borrower_logout(true, false);
+    } else {
+      // Card scanned
+      if (!Borrower_isLoggedIn()) {
+        // New card
+        Screen_displayEnterPIN(0);
+      }
+    }
+
+    CardReader.currentId = id ?? "";
+  }
+
+  function CardReader_resetAttempts() {
+    CardReader.attempts = 0;
+  }
+
+  function CardReader_validatePIN(pin: string[]) {
+    Library_validateCard(CardReader.currentId, pin);
+  }
+
+  function CardReader_PINfailed() {
+    // TODO: Force remove card after 3 failed attempts
+    Screen_displayEnterPIN(++CardReader.attempts);
+  }
+
+  //#endregion
+
+  //#region Library /////
+
+  const Library = {
+    cards,
+  };
+
+  function Library_validateCard(cardId: string, pin: string[]) {
+    const card = Library.cards.find((card) => card["@id"] === cardId);
+    if (card && card.identifier === hash(pin.join(""))) {
+      Borrower_login(card._owner);
+    } else {
+      CardReader_PINfailed();
+    }
+  }
+
+  //#endregion
+
+  //#region Screen /////
+
+  function Screen_displayWelcome() {
+    Screen.display({ display: Display.Welcome });
+  }
+
+  function Screen_displayEnterPIN(attempts: number) {
+    Screen.display({ display: Display.EnterPIN, attempts });
+  }
+
+  function Screen_displayItems(items: { title: string; expires: Date }[]) {
+    Screen.display({ display: Display.Items, items });
+  }
+
+  function Screen_displayThankYou(forced: boolean) {
+    if (forced && Screen.currentState().display === Display.ThankYou) {
+      Screen_displayWelcome();
+    } else {
+      Screen.display({ display: Display.ThankYou });
+      if (forced) Screen__displayNext({ display: Display.Welcome });
+    }
+  }
+
+  function Screen_displayError(error: Error) {
+    // Log out user
+    rebind(undefined);
+    Screen.display({ display: Display.Error, error });
+    Screen__displayNext({ display: Display.Welcome }, 10000);
+  }
+
+  function Screen__displayNext(nextState: ScreenState, delay = 5000) {
+    const currentState = Screen.currentState();
+    setTimeout(() => {
+      if (currentState === Screen.currentState()) Screen.display(nextState);
+    }, delay);
+  }
+
+  //#endregion
+
+  //#region Printer /////
+
+  async function Printer_printReceipt(
+    items: { title: string; expires: Date }[]
+  ) {
+    if (items.length) {
+      await Printer__printLine(new Date().toISOString().slice(0, 10));
+      await Printer__printLine("");
+      for (const item of items) {
+        await Printer__printLine(item.title);
+        await Printer__printLine(
+          "Return on " + item.expires.toISOString().slice(0, 10)
+        );
+        await Printer__printLine("");
+      }
+    }
+  }
+
+  async function Printer__printLine(line: string) {
+    Printer.print(line);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  //#endregion
+
+  /**
+   * Reset the Context state, rebind to a new user or undefined (not logged in).
+   */
+  function rebind(userId: string | undefined) {
+    Borrower = { "@id": userId ?? "", "@type": "Person", items: [] };
+    CardReader_resetAttempts();
+  }
+
+  {
+    // Context start
+    rebind(undefined);
+    Screen_displayWelcome();
+
+    return {
+      cardScanned(id: string | undefined) {
+        CardReader_cardScanned(id);
+      },
+
+      itemScanned(id: string | undefined) {
+        Borrower_borrowItem(id);
+      },
+
+      pinEntered(pin: string[]) {
+        CardReader_validatePIN(pin);
+      },
+
+      finish(printReceipt: boolean) {
+        Borrower_logout(false, printReceipt);
+      },
+    };
+  }
+}
+```

package/docs/typescript/instructions.md

@@ -0,0 +1,59 @@
+## TypeScript-Specific Implementation
+
+### Context Implementation
+
+- A Context is a function annotated with `@DCI-context`. If that doesn't exist, _do not_ apply DCI.
+- Contexts and their RoleMethods can be async functions when needed.
+
+### Role Contracts
+
+- Use literal types as Role Contracts, so the code can be understood without deeper type knowledge. Example:
+
+```ts
+const Form: { action: string } = event.target;
+```
+
+- EXCEPTION: If the types are well-known, like the JavaScript Web APIs, you can reference them directly (e.g., `Page`, `HTMLElement`). Example:
+
+```ts
+const Page: Page = await Browser.newPage();
+```
+
+- If an object is passed to the Context function that fits the mental model of a Context Role, the Role should be defined from it with the Role Contract as the parameter type. This is the ONLY case RoleMethods should exist in the Context without their Role defined immediately before them. Example:
+
+```ts
+/**
+ * @DCI-context
+ * A speaker proclaims something to the world, that dutifully notes it
+ */
+function HelloWorld(
+  Speaker: { phrase: string },
+  World: { log: (msg: unknown) => void },
+) {
+  function Speaker_proclaim() {
+    World_note(Speaker.phrase);
+  }
+
+  function World_note(phrase: string) {
+    World.log(phrase);
+  }
+
+  Speaker_proclaim();
+}
+```
+
+### RoleMethod Naming
+
+- RoleMethods are functions within the Context scope, named `Role_method()`. Example: `Speaker_proclaim()`, `World_note()`
+- Internal (private) RoleMethods, callable only by RoleMethods in the same Role, use a double underscore: `Role__method()`.
+
+### Role Organization
+
+- Use `//#region RoleName Role /////` and `//#endregion` comments to group RoleMethods by Role.
+- This enables easy folding/unfolding of Roles in the editor.
+
+### Type Annotations
+
+- Use `@DCI-context` JSDoc tag to mark Context functions.
+- Clarify Role Contracts with explicit types inline.
+- Prefer inline literal types over separate type declarations for Role Contracts.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "dci-mcp",
+  "version": "0.1.0",
+  "description": "MCP Server generating code that adheres to DCI architecture principles.",
+  "type": "module",
+  "bin": {
+    "dci-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node --experimental-strip-types src/index.ts",
+    "dev": "pnpm build && pnpm link",
+    "inspector": "pnpx @modelcontextprotocol/inspector dci-mcp"
+  }
+}