@fluttersdk/mcp 1.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @fluttersdk/mcp
+
+HTTP-to-stdio bridge for the [FlutterSDK Docs MCP server](https://mcp.fluttersdk.com/).
+
+The upstream server at `mcp.fluttersdk.com` speaks the Streamable HTTP MCP transport.
+This bridge wraps it with a stdio transport so clients that do not support
+Streamable HTTP natively (Claude Desktop, older Codex CLI, any shell-based MCP host)
+can connect to it without modification.
+
+## When to use
+
+Use this bridge when your MCP client:
+
+- Only supports stdio MCP transport (e.g. Claude Desktop, older Cursor versions).
+- Cannot talk to HTTP-based MCP servers directly.
+- Needs a proxy in front of the upstream for allowlist control.
+
+If your client natively supports Streamable HTTP, point it directly at
+`https://mcp.fluttersdk.com/` instead.
+
+## Install and run
+
+```bash
+npx @fluttersdk/mcp
+```
+
+The bridge starts a local stdio MCP server. It does not connect to the upstream
+until the first `tools/list` or `tools/call` request arrives (lazy connect).
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FLUTTERSDK_MCP_URL` | `https://mcp.fluttersdk.com/` | Upstream MCP server URL |
+| `BRIDGE_ALLOW_TOOLS` | `search-docs` | Comma-separated list of tool names to expose. Use `*` for unrestricted access. |
+
+### Examples
+
+Expose only the default `search-docs` tool (default behavior):
+
+```bash
+npx @fluttersdk/mcp
+```
+
+Expose all tools the upstream provides:
+
+```bash
+BRIDGE_ALLOW_TOOLS=* npx @fluttersdk/mcp
+```
+
+Point at a local upstream during development:
+
+```bash
+FLUTTERSDK_MCP_URL=http://localhost:8000/ npx @fluttersdk/mcp
+```
+
+## Claude Desktop configuration
+
+Add the following to your Claude Desktop `claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "fluttersdk": {
+            "command": "npx",
+            "args": ["@fluttersdk/mcp"]
+        }
+    }
+}
+```
+
+To allow all upstream tools:
+
+```json
+{
+    "mcpServers": {
+        "fluttersdk": {
+            "command": "npx",
+            "args": ["@fluttersdk/mcp"],
+            "env": {
+                "BRIDGE_ALLOW_TOOLS": "*"
+            }
+        }
+    }
+}
+```
+
+## Available tools
+
+The upstream server exposes one tool by default (and the bridge allowlist matches it):
+
+| Tool | Description |
+|------|-------------|
+| `search-docs` | Search Flutter and Dart documentation. Accepts `queries`, `packages`, `version`, and `token_limit` parameters. |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Filters a list of tools by the allowlist string.
+ *
+ * @param tools - The full tool list returned by the upstream server.
+ * @param allowlist - Comma-separated tool names, or "*" for unrestricted access.
+ * @returns The filtered subset of tools.
+ */
+export declare function filterTools(tools: Tool[], allowlist: string): Tool[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAMA,OAAO,EAAiD,KAAK,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAK9G;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,CAUpE"}

package/dist/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+const UPSTREAM_URL = process.env["FLUTTERSDK_MCP_URL"] ?? "https://mcp.fluttersdk.com/";
+const ALLOW_TOOLS = process.env["BRIDGE_ALLOW_TOOLS"] ?? "search-docs";
+/**
+ * Filters a list of tools by the allowlist string.
+ *
+ * @param tools - The full tool list returned by the upstream server.
+ * @param allowlist - Comma-separated tool names, or "*" for unrestricted access.
+ * @returns The filtered subset of tools.
+ */
+export function filterTools(tools, allowlist) {
+    if (allowlist.trim() === "*") {
+        return tools;
+    }
+    const allowed = new Set(allowlist.split(",").map((name) => name.trim()).filter(Boolean));
+    return tools.filter((tool) => allowed.has(tool.name));
+}
+const server = new Server({ name: "fluttersdk-bridge", version: "1.1.0" }, { capabilities: { tools: {} } });
+// Lazily initialized upstream client and cached tool list.
+let upstreamClient = null;
+let cachedTools = null;
+async function getUpstreamClient() {
+    if (upstreamClient !== null) {
+        return upstreamClient;
+    }
+    const client = new Client({ name: "fluttersdk-bridge-client", version: "1.1.0" });
+    const transport = new StreamableHTTPClientTransport(new URL(UPSTREAM_URL));
+    await client.connect(transport);
+    upstreamClient = client;
+    return client;
+}
+async function getFilteredTools() {
+    if (cachedTools !== null) {
+        return cachedTools;
+    }
+    const client = await getUpstreamClient();
+    const result = await client.listTools();
+    cachedTools = filterTools(result.tools, ALLOW_TOOLS);
+    return cachedTools;
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = await getFilteredTools();
+    return { tools };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tools = await getFilteredTools();
+    const allowed = tools.some((tool) => tool.name === request.params.name);
+    if (!allowed) {
+        throw new Error(`Tool "${request.params.name}" is not available through this bridge.`);
+    }
+    const client = await getUpstreamClient();
+    return client.callTool(request.params);
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@fluttersdk/mcp",
+    "version": "1.1.0",
+    "description": "HTTP↔stdio bridge for the FlutterSDK Docs MCP server (mcp.fluttersdk.com)",
+    "author": "Anilcan Cakir <anilcan.cakir@gmail.com>",
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "fluttersdk-mcp": "dist/index.js"
+    },
+    "main": "dist/index.js",
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "lint": "eslint src/",
+        "test": "vitest run",
+        "start": "node dist/index.js"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.0",
+        "zod": "^3.23.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "typescript": "^5.6.0",
+        "vitest": "^2.0.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/fluttersdk/ai",
+        "directory": "mcps/fluttersdk-mcp"
+    },
+    "keywords": [
+        "mcp",
+        "flutter",
+        "fluttersdk",
+        "bridge",
+        "stdio",
+        "streamable-http"
+    ]
+}