@easingwizard/mcp-server 1.1.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2025 Matthias Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software, subject to the following conditions:
+
+The Software may be used in commercial or non-commercial projects, provided that the Software is not the primary selling point or core value of any commercial product or service.
+The Software may not be sold, licensed, or distributed as a standalone product or as the main feature of a commercial offering.
+Inclusion of the Software in a larger work is permitted, provided the larger work offers substantial additional functionality and value beyond the Software itself.
+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,51 +1,48 @@
 # Easing Wizard MCP Server
 
-A Model Context Protocol (MCP) server for the [Easing Wizard](https://easingwizard.com). This server enables AI assistants to generate various CSS easing curves: Bézier, Spring, Bounce, Wiggle, and Overshoot.
+Generate CSS easing curves from an AI coding assistant: Bézier, Spring, Bounce, Wiggle, and Overshoot. The seven tools use the same calculation library as [Easing Wizard](https://easingwizard.com), returning CSS, Tailwind classes, SVG geometry, and share links.
 
-## Features
+The stdio server calculates everything locally. It does not call the REST API, need an account, or write files. The same tools can also run behind the API's Streamable HTTP endpoint.
 
-- **Preset curves**: Access predefined easing curves filtered by type
-- **Bézier curves**: Create custom cubic Bézier curves with control points
-- **Spring curves**: Physics-based spring animations with mass, stiffness, and damping
-- **Bounce curves**: Bouncing animations with configurable bounces and damping
-- **Wiggle curves**: Oscillating animations with configurable wiggles and damping
-- **Overshoot curves**: Curves that overshoot the target before settling
+## Requirements and release status
 
-## Setup
+- Node.js **22.14 or later** for the local npm server.
+- An MCP client supporting stdio or Streamable HTTP.
+- This checkout targets MCP **2026-07-28**, with compatibility for clients using the 2025 `initialize` handshake.
 
-### Claude Desktop
+The npm examples below run the latest **published** package. Publishing a new package and deploying the HTTP endpoint are separate release steps; use the local checkout instructions to test changes before release. For reproducible installations, replace `@easingwizard/mcp-server` with `@easingwizard/mcp-server@<published-version>`.
 
-Add to your `claude_desktop_config.json`:
+## Connect over stdio
 
-```json
-{
-  "mcpServers": {
-    "easingwizard": {
-      "command": "npx",
-      "args": ["-y", "@easingwizard/mcp-server"]
-    }
-  }
-}
+The client launches and stops the process. A global npm installation or a separately running daemon is unnecessary.
+
+### Codex
+
+```sh
+codex mcp add easingwizard -- npx -y @easingwizard/mcp-server
+codex mcp list
 ```
 
-### VS Code
+Equivalent `~/.codex/config.toml` configuration:
 
-Add to your MCP configuration `.vscode/mcp.json`:
+```toml
+[mcp_servers.easingwizard]
+command = "npx"
+args = ["-y", "@easingwizard/mcp-server"]
+```
 
-```json
-{
-  "servers": {
-    "easingwizard": {
-      "command": "npx",
-      "args": ["-y", "@easingwizard/mcp-server"]
-    }
-  }
-}
+### Claude Code
+
+```sh
+claude mcp add --transport stdio --scope user easingwizard -- npx -y @easingwizard/mcp-server
+claude mcp list
 ```
 
-### Other MCP Clients
+Run `/mcp` in Claude Code to check the connection. The [Claude plugin](../claude-plugin/README.md) adds workflows for recommending and auditing animation curves alongside the tools. Install either its bundled server or a standalone server entry to avoid duplicate tools.
+
+### Claude Desktop
 
-For other MCP-compatible applications, use the standard configuration format:
+Add to `claude_desktop_config.json`, then restart the app:
 
 ```json
 {
@@ -58,89 +55,70 @@ For other MCP-compatible applications, use the standard configuration format:
 }
 ```
 
-## Available Tools
-
-The MCP server provides the following tools for AI assistants:
-
-### `getPresets`
-
-Retrieves available preset easing curves, optionally filtered by type.
-
-**Parameters:**
-
-- `type` (optional): Filter by easing type (`BEZIER`, `SPRING`, `BOUNCE`, `WIGGLE`, `OVERSHOOT`)
+### VS Code
 
-**Example:**
+Add to `.vscode/mcp.json`:
 
 ```json
 {
-  "name": "getPresets",
-  "arguments": {
-    "type": "BEZIER"
+  "servers": {
+    "easingwizard": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@easingwizard/mcp-server"]
+    }
   }
 }
 ```
 
-### `getCurveById`
-
-Retrieves a specific easing curve by its unique ID.
+Other clients use their own configuration format. The common launch command is `npx -y @easingwizard/mcp-server`; `mcpServers` is not a universal configuration key.
 
-**Parameters:**
+## Connect over HTTP
 
-- `id` (required): The unique ID of the easing curve
+The API application mounts a stateless Streamable HTTP handler at `/mcp`. After starting the local API, connect with:
 
-**Example:**
-
-```json
-{
-  "name": "getCurveById",
-  "arguments": {
-    "id": "0a0d.25e.1f.75g.914"
-  }
-}
+```sh
+codex mcp add easingwizard-http --url http://127.0.0.1:3000/mcp
+claude mcp add --transport http --scope user easingwizard-http http://127.0.0.1:3000/mcp
 ```
 
-### `createBezierCurve`
+Use your deployed HTTPS `/mcp` URL for remote access. The planned public address is `https://api.easingwizard.com/mcp`; it becomes available after the API deployment and is not enabled merely by publishing the npm package. HTTP clients need no local Node.js installation. The REST endpoints themselves are not MCP endpoints.
 
-Creates a custom cubic Bézier easing curve.
+The handler supports both protocol generations. It uses bounded requests (64 KiB), returns JSON for current-protocol tool requests, and does not hold sessions or subscriptions. The API host supplies Origin validation, CORS, and request rate limits. There is no authentication because these tools only calculate public curves and access no private account data.
 
-**Parameters:**
+To embed it in another fetch-based server:
 
-- `x1` (0-1): First control point X coordinate
-- `y1` (-1 to 2): First control point Y coordinate
-- `x2` (0-1): Second control point X coordinate
-- `y2` (-1 to 2): Second control point Y coordinate
+```ts
+import { createEasingWizardMcpHandler } from '@easingwizard/mcp-server/http';
 
-**Example:**
-
-```json
-{
-  "name": "createBezierCurve",
-  "arguments": {
-    "x1": 0.25,
-    "y1": 0.1,
-    "x2": 0.75,
-    "y2": 0.9
-  }
-}
+const mcp = createEasingWizardMcpHandler();
+// Mount mcp.fetch(request) at /mcp behind Origin/Host checks and rate limits.
+// Call await mcp.close() during shutdown.
 ```
 
-### `createSpringCurve`
+`@easingwizard/mcp-server/server` also exports `createEasingWizardServer()` for hosts needing their own transport wiring.
 
-Creates a spring-based easing curve with physics parameters.
+## Tools
 
-**Parameters:**
+All tools are read-only and have no persistent side effects. Names are case-sensitive.
 
-- `mass` (1-5): Mass of the spring system
-- `stiffness` (0-100): Spring stiffness
-- `damping` (0-100): Damping force
-- `accuracy` (`LOW`, `MEDIUM`, `HIGH`, `ULTRA`): Calculation precision
+| Tool                     | Inputs                                                                         |
+| ------------------------ | ------------------------------------------------------------------------------ |
+| `get_presets`            | Optional `type`: `BEZIER`, `SPRING`, `BOUNCE`, `WIGGLE`, or `OVERSHOOT`        |
+| `get_curve_by_id`        | `id`: curve ID returned by a tool or the visual editor                         |
+| `create_bezier_curve`    | `x1`, `x2`: 0–1; `y1`, `y2`: −1–2                                              |
+| `create_spring_curve`    | `mass`: 1–5; `stiffness`, `damping`: 0–100; `accuracy`                         |
+| `create_bounce_curve`    | `bounces`: 1–10; optional `mass`: 1–5, default 1; `damping`: 0–100; `accuracy` |
+| `create_wiggle_curve`    | `wiggles`: 1–10; optional `mass`: 1–5, default 1; `damping`: 0–100; `accuracy` |
+| `create_overshoot_curve` | `style`: `IN`, `OUT`, or `IN_OUT`; `mass`: 1–5; `damping`: 0–100; `accuracy`   |
 
-**Example:**
+`accuracy` is `LOW`, `MEDIUM`, `HIGH`, or `ULTRA`; use `HIGH` for normal UI animations. Tools advertise their complete input and output schemas. Invalid arguments or curve IDs produce `isError: true` results so the assistant can correct the request.
+
+Example `tools/call` parameters:
 
 ```json
 {
-  "name": "createSpringCurve",
+  "name": "create_spring_curve",
   "arguments": {
     "mass": 2.5,
     "stiffness": 50,
@@ -150,84 +128,53 @@ Creates a spring-based easing curve with physics parameters.
 }
 ```
 
-### `createBounceCurve`
-
-Creates a bouncing easing curve.
-
-**Parameters:**
-
-- `bounces` (1-10): Number of bounces
-- `damping` (0-100): Bounce damping
-- `accuracy` (`LOW`, `MEDIUM`, `HIGH`, `ULTRA`): Calculation precision
-
-### `createWiggleCurve`
-
-Creates an oscillating wiggle curve.
-
-**Parameters:**
-
-- `wiggles` (1-10): Number of oscillations
-- `damping` (0-100): Oscillation damping
-- `accuracy` (`LOW`, `MEDIUM`, `HIGH`, `ULTRA`): Calculation precision
+Curve responses contain:
 
-### `createOvershootCurve`
+- `output.css`: ready-to-use `cubic-bezier()` or `linear()`.
+- `output.tailwind_css`: Tailwind arbitrary easing class.
+- `output.svg_path` or `output.svg_polyline`: curve geometry.
+- `output.suggested_duration_ms`: suggested duration range for non-Bézier curves.
+- `id`, normalized `input`, `type`, `generated_at`, and `links.share_url`.
 
-Creates an overshoot easing curve.
+Results include `structuredContent` and a JSON text fallback. Filter `get_presets` by type when possible to keep its response small. A curve ID encodes parameters; it does not reference a database record.
 
-**Parameters:**
+Try: “Create a subtle spring easing for a dropdown, return the Tailwind class and a suggested duration.”
 
-- `style` (`IN`, `OUT`, `IN_OUT`): Animation style
-- `mass` (1-5): Mass parameter
-- `damping` (0-100): Damping force
-- `accuracy` (`LOW`, `MEDIUM`, `HIGH`, `ULTRA`): Calculation precision
+## Local development and verification
 
-## Output Formats
+From the repository root:
 
-All easing curve tools return comprehensive data including:
-
-- **CSS Functions**: Ready-to-use `cubic-bezier()` or `linear()` functions
-- **Tailwind CSS**: Compatible easing class names
-- **SVG Paths**: Vector graphics for curve visualization
-- **Metadata**: Unique IDs, timestamps, and reference links
-
-## Development
-
-If you want to contribute or modify the server:
-
-```bash
-# Clone the repository
-git clone https://github.com/roydigerhund/easingwizard.git
-cd easingwizard/apps/mcp
-
-# Install dependencies
-pnpm install
-
-# Build the server
-pnpm build
+```sh
+pnpm install --frozen-lockfile
+pnpm --filter easingwizard-core build
+pnpm --filter @easingwizard/mcp-server build
+pnpm --filter @easingwizard/mcp-server typecheck
+pnpm --filter @easingwizard/mcp-server test
+```
 
-# Test the server
-pnpm watch
+Test a checkout directly, using its absolute path:
 
-# Inspect the MCP tool
-pnpm inspect
+```sh
+codex mcp add easingwizard-local -- node /absolute/path/to/easingwizard/apps/mcp/dist/index.js
 ```
 
-## Error Handling
+For interactive inspection:
 
-The server provides detailed error messages for:
+```sh
+pnpm --filter @easingwizard/mcp-server inspect
+```
 
-- Invalid parameter ranges or types
-- Malformed curve configurations
-- MCP protocol errors
-- Internal processing failures
+The contract tests run real stdio clients and in-process HTTP clients for both protocol generations. They exercise all seven tools, validate outputs against the advertised JSON Schemas, reconstruct curves from IDs, check invalid arguments and recovery, and enforce HTTP body limits. Test clients close their child processes when finished.
 
-## License
+The build bundles the shared curve library while keeping the SDK and Zod as runtime dependencies. The server identity derives its version from `package.json`. Keep `dist` built before testing or publishing; changes to the shared core require rebuilding it first. `prepack` rebuilds both packages for publication.
 
-MIT License - see [LICENSE](LICENSE) file for details.
+## Protocol references
 
-## Links
+- [MCP versioning](https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning)
+- [TypeScript SDK: stdio](https://ts.sdk.modelcontextprotocol.io/v2/serving/stdio.html)
+- [TypeScript SDK: HTTP](https://ts.sdk.modelcontextprotocol.io/v2/serving/http.html)
+- [Protocol migration and compatibility](https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.html)
+- [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp)
+- [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp)
 
-- **Website**: [Easing Wizard](https://easingwizard.com)
-- **Repository**: [GitHub](https://github.com/roydigerhund/easingwizard)
-- **Issues**: [Report bugs](https://github.com/roydigerhund/easingwizard/issues)
-- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io)
+See [LICENSE](LICENSE) for the project's license and commercial-use conditions.

package/dist/http.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Stateless Streamable HTTP handler for current and legacy MCP clients.
+ * The hosting application must apply Origin/Host validation and rate limits.
+ */
+export declare function createEasingWizardMcpHandler(): import("@modelcontextprotocol/server").McpHttpHandler;