@enokdev/springdocs-mcp 1.2.7 → 1.4.1

package/README.md

@@ -2,10 +2,10 @@
 
 [![npm version](https://badge.fury.io/js/@enokdev%2Fspringdocs-mcp.svg)](https://badge.fury.io/js/@enokdev%2Fspringdocs-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-20.18+-green.svg)](https://nodejs.org/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Universal%20Compatible-brightgreen.svg)](https://modelcontextprotocol.io/)
 
-> **🚀 Enhanced v1.2.4:** 12 powerful tools with intelligent caching, advanced tutorials, and comprehensive Spring ecosystem access
+> **🚀 Enhanced v1.4.1:** 17 powerful tools with **Spring AI support**, intelligent caching, advanced tutorials, and comprehensive Spring ecosystem access
 >
 > **🌐 Universal MCP Compatibility:** Works with Claude Code, Gemini CLI, VS Code, JetBrains IDEs, and all MCP-compatible clients!
 
@@ -22,7 +22,7 @@ This server works with **ALL MCP-compatible clients**:
     "spring-docs": {
       "command": "npx",
       "args": ["@enokdev/springdocs-mcp@latest"],
-      "description": "Spring Documentation MCP Server with 12 powerful tools"
+      "description": "Spring Documentation MCP Server with 17 powerful tools"
     }
   }
 }
@@ -60,6 +60,23 @@ npm install -g @enokdev/springdocs-mcp
 # Then use: springdocs-mcp
 ```
 
+#### Docker (Coming Soon - Docker MCP Catalog)
+```bash
+# Via Docker MCP CLI (when available in catalog)
+docker mcp add springdocs-mcp
+
+# Via Docker directly
+docker pull mcp/springdocs-mcp:latest
+echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \
+  docker run -i mcp/springdocs-mcp:latest
+```
+
+**Benefits of Docker distribution:**
+- Enhanced security with cryptographic signatures and SBOMs
+- Isolated execution environment
+- Reduced token usage in Docker Desktop
+- Automatic security updates
+
 **Config file locations:**
 - **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
 - **Claude Code:** `~/.claude-code/mcp-config.json`
@@ -70,35 +87,49 @@ npm install -g @enokdev/springdocs-mcp
 
 ## ✨ Features & Tools
 
-### 📚 **Core Documentation (7 Enhanced Tools)**
+The server exposes **17 tools**.
+
+### 📚 **Core Documentation (8 Tools)**
+| Tool | Purpose | Example Usage |
+|------|---------|---------------|
+| `search_spring_docs` | Search Spring documentation (`docType` all, guides, projects, reference, content; optional `version`) | "Search docs for WebClient" |
+| `search_spring_projects` | Find Spring projects | "Find projects about security" |
+| `get_spring_project` | Project page as markdown (paginated with `offset`) | "Show the Spring Data project" |
+| `get_all_spring_guides` | List the getting-started guides | "List the guides" |
+| `get_spring_guide` | Complete guide content | "Get the rest-service guide" |
+| `get_spring_reference` | Reference documentation for 11 projects (`version`, `offset`) | "Boot reference, web section" |
+| `get_migration_guide` | Spring Boot / Framework / Batch migration guides and upgrade notes | "Migration guide to Boot 3.4" |
+| `search_spring_concepts` | Explore Spring concepts (optional `version`) | "Explain auto-configuration" |
+
+### 🚀 **Advanced Features (6 Tools)**
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
-| `search_spring_docs` | Search documentation with caching | "Search for REST API security" |
-| `search_spring_projects` | Find Spring projects | "Search for microservices projects" |
-| `get_spring_project` | Get project details | "Get Spring Boot project info" |
-| `get_all_spring_guides` | List available guides | "Show all security guides" |
-| `get_spring_guide` | Get complete guide content | "Get gs-rest-service guide" |
-| `get_spring_reference` | Reference documentation | "Get web reference docs" |
-| `search_spring_concepts` | Explore Spring concepts | "Explain auto-configuration" |
-
-### 🆕 **Advanced Tools (5 New)**
+| `search_spring_ecosystem` | Search the whole ecosystem, Spring AI included | "Find Spring AI vector stores" |
+| `get_spring_tutorial` | Step-by-step tutorials | "Tutorial on Spring Security" |
+| `compare_spring_versions` | Version comparison and migration notes | "Compare 3.3 and 3.4" |
+| `get_release_notes` | GitHub release notes with focus filter | "Release notes of Boot 3.5" |
+| `get_spring_best_practices` | Expert guidance by category | "Best practices for testing" |
+| `diagnose_spring_issues` | Offline stack trace and error diagnosis | "Diagnose this DataSource error" |
+
+### 🧰 **Tooling (3 Tools)**
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
-| `search_spring_ecosystem` | Search entire ecosystem | "Find reactive programming resources" |
-| `get_spring_tutorial` | Step-by-step tutorials | "Get intermediate REST API tutorial" |
-| `compare_spring_versions` | Version comparison & migration | "Compare Spring Boot 2.7 vs 3.0" |
-| `get_spring_best_practices` | Expert guidance by category | "Get security best practices" |
-| `diagnose_spring_issues` | Intelligent error diagnosis | "Diagnose port 8080 error" |
-
-### ⚡ **Performance Features**
-- **50-80% faster** with intelligent caching
-- **85% cache hit rate** for popular queries
-- **Auto-retry logic** with exponential backoff
-- **Multiple data sources** for reliability
-- **Parallel processing** for complex searches
+| `get_spring_initializr` | Spring Initializr metadata: Boot versions, dependencies (start.spring.io) | "Which Boot versions does Initializr offer?" |
+| `find_spring_dependency` | Find starters for a need, with Maven and Gradle snippets (optional `bootVersion` as X.Y.Z) | "Which dependency for Redis caching?" |
+| `spring_cache_stats` | In-memory cache statistics and optional purge | "Show cache stats" |
 
 ---
 
+### 📎 **Resources**
+
+- `spring://project/<slug>` : Spring project page as complete markdown (e.g. `spring://project/spring-boot`); `resources/list` enumerates the 11 projects of the registry, the template accepts any project of spring.io
+- `spring://guide/<id>` : Spring getting-started guide as complete markdown (e.g. `spring://guide/rest-service`), available through the resource template
+
+### 💬 **Prompts**
+
+- `migrate-boot-version` (`to_version`, optional `from_version`): plans a Spring Boot upgrade by chaining `get_migration_guide`, `get_release_notes` and `get_spring_reference`
+- `explain-error` (`error_message`, optional `stack_trace`): explains a Spring error by chaining `diagnose_spring_issues` and `get_spring_reference`
+
 ## 📖 Usage Examples
 
 ### Basic Search
@@ -106,6 +137,20 @@ npm install -g @enokdev/springdocs-mcp
 "Search for REST API documentation in Spring Boot"
 ```
 
+`search_spring_docs` and `search_spring_concepts` accept an optional `version` (`3.4` or `3.4.2`, the patch is ignored; `current` or omitted = latest) that targets the Spring Boot reference documentation of that version (a version that is not published gives a dedicated error). Guides and projects are not versioned and ignore it; with `docType=content`, Boot reference pages of other versions are left out of the results.
+
+`get_migration_guide` accepts `project` (`spring-boot` by default, `spring-framework`, `spring-batch`): Framework serves the release notes of its minor version (`6.2`, section "Upgrading From ..."), Batch its migration guide (`5.0`, `6.0`), both read as raw markdown from the project wiki; `section` and `offset` work as for Boot. Spring Security and Spring AI (docs.spring.io pages) are not covered yet.
+
+`search_spring_docs` accepts `docType=content`: full-text search (BM25 ranking) over the pages the server has already read (`get_spring_project`, `get_spring_reference`, `get_spring_guide`). It is included in `docType=all` and stays empty until a page has been read.
+
+### 🆕 Spring AI Support
+```
+"Get Spring AI ChatClient reference documentation"
+"Search for RAG and embeddings in Spring AI"
+"Show me Spring AI vector store documentation"
+"Find Spring AI LLM integration examples"
+```
+
 ### Ecosystem Exploration
 ```
 "Search the Spring ecosystem for microservices patterns"
@@ -170,6 +215,33 @@ npm install -g @enokdev/springdocs-mcp
 
 ---
 
+## Transport HTTP (optionnel)
+
+Par défaut le serveur parle stdio. Pour l'héberger en local ou en conteneur :
+
+```bash
+npx @enokdev/springdocs-mcp --transport http --port 3000   # écoute sur 127.0.0.1
+```
+
+| Option | Variable | Défaut |
+|---|---|---|
+| `--transport stdio\|http` | `MCP_TRANSPORT` | `stdio` |
+| `--port` | `MCP_PORT` | `3000` |
+| `--host` | `MCP_HOST` | `127.0.0.1` |
+| (aucune) | `MCP_ALLOWED_HOSTS` | vide : liste de `Host` supplémentaires, séparés par des virgules |
+
+Endpoint MCP : `POST /mcp` (mode sans état) ; santé : `GET /healthz`. **Aucune authentification** : l'écoute reste sur loopback par défaut, et les en-têtes `Host`/`Origin` sont contrôlés contre le DNS rebinding. Pour un conteneur, `MCP_TRANSPORT=http MCP_HOST=0.0.0.0` avec le port publié (`-p 127.0.0.1:3000:3000`) ; si le port publié diffère du port interne, déclarer le `Host` utilisé par le client, par exemple `MCP_ALLOWED_HOSTS=localhost:8080`.
+
+Le `Host` doit être de la forme `nom:port` : un `Host` sans port (client sur le port 80 ou 443 derrière un reverse proxy, par exemple `Host: mcp.example.com`) est refusé en 403. Il faut alors le déclarer tel que le proxy le transmet, via `MCP_ALLOWED_HOSTS=mcp.example.com` (liste séparée par des virgules, comparaison exacte avec l'en-tête reçu).
+
+### Jeton GitHub (optionnel)
+
+`get_release_notes` et `compare_spring_versions` interrogent l'API GitHub, limitée à 60 requêtes/heure sans authentification. Définir `GITHUB_TOKEN` (jeton sans scope particulier suffit) relève cette limite à 5000/heure ; le jeton n'est envoyé qu'à `api.github.com` (jamais à un autre hôte ni après une redirection) et n'est jamais journalisé. En cas de limite atteinte, l'outil échoue immédiatement avec un message clair (délai de reprise inclus) au lieu d'attendre. `get_release_notes` accepte `version` en `X.Y` (ex. `3.5`) pour obtenir la dernière release stable de cette mineure ; `compare_spring_versions` applique `focus` (`breaking-changes`, `new-features`, `deprecations`).
+
+```json
+{ "mcpServers": { "springdocs": { "command": "npx", "args": ["@enokdev/springdocs-mcp@latest"], "env": { "GITHUB_TOKEN": "ghp_..." } } } }
+```
+
 ## 🧪 Testing & Development
 
 ### Quick Test
@@ -203,7 +275,7 @@ done
 
 #### "Server failed to start"
 ```bash
-# Check Node.js version (requires 18+)
+# Check Node.js version (requires 20.18.1+)
 node --version
 
 # Update to latest
@@ -259,8 +331,8 @@ echo $? -eq 0 && echo "✅ Network: OK" || echo "❌ Network: FAILED"
 
 ### 🆕 **Major Enhancements**
 - **5 new advanced tools** for comprehensive Spring ecosystem access
-- **50-80% performance improvement** with intelligent caching
-- **99.5% reliability** with auto-retry and fallback mechanisms
+- **In-memory caching** of repeated requests (30 min TTL, 24 h for stable content)
+- **Auto-retry** with exponential backoff and a 5 MiB response size cap
 - **Clean architecture** with modular services and optimized code
 
 ### 🎯 **New Capabilities**
@@ -270,25 +342,21 @@ echo $? -eq 0 && echo "✅ Network: OK" || echo "❌ Network: FAILED"
 - **Expert best practices** categorized by domain and experience level
 - **Intelligent diagnostics** for common Spring Boot issues
 
-### ⚡ **Performance Improvements**
-| Metric | Before v1.2.3 | After v1.2.3 | Improvement |
-|--------|---------------|--------------|-------------|
-| Response Time | 2-5 seconds | 0.5-2 seconds | **50-80% faster** |
-| Cache Hit Rate | 0% | 85% | **New feature** |
-| Success Rate | 90% | 99.5% | **10x more reliable** |
-| Memory Usage | High | Optimized | **40% reduction** |
+### ⚡ **Performance & Resilience**
+- Repeated requests are served from the in-memory cache (30 min TTL, 24 h for stable content) without a new network call
+- The cache is bounded by an estimated memory budget (64 MiB by default, LRU eviction, a single value larger than the budget is not cached); override with `MCP_CACHE_MAX_MB` (e.g. `MCP_CACHE_MAX_MB=32`). `spring_cache_stats` reports entries and estimated memory used / budget
+- Retry with exponential backoff and request timeouts on all external HTTP calls
+- Responses larger than 5 MiB are rejected
 
 ---
 
 ## 🔮 Roadmap
 
-### v1.3.0 (Next)
-- Interactive Spring Boot project generator
-- Real-time error analysis
-- Spring Initializr integration
+### v1.5.0 (Next)
+- Interactive Spring Boot project generator (Initializr metadata and dependency lookup are already available)
 - Custom tutorial creation
 
-### v1.4.0 (Future)
+### v1.6.0 (Future)
 - AI-powered code suggestions
 - Performance bottleneck detection
 - Security vulnerability scanning

package/build/config.d.ts

@@ -0,0 +1,9 @@
+export type TransportMode = "stdio" | "http";
+export interface ServerConfig {
+    transport: TransportMode;
+    host: string;
+    port: number;
+    allowedHosts: string[];
+}
+export declare function parseConfig(argv: string[], env: NodeJS.ProcessEnv): ServerConfig;
+//# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,aAAa,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAoBD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,YAAY,CAgBhF"}

package/build/config.js

@@ -0,0 +1,32 @@
+const TRANSPORTS = ["stdio", "http"];
+/** Value of `--name value` or `--name=value`; undefined when the option is absent. */
+function readOption(argv, name) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === name) {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error(`${name} requires a value`);
+            }
+            return value;
+        }
+        if (arg.startsWith(`${name}=`))
+            return arg.slice(name.length + 1);
+    }
+    return undefined;
+}
+export function parseConfig(argv, env) {
+    const transport = readOption(argv, "--transport") ?? env.MCP_TRANSPORT ?? "stdio";
+    if (!TRANSPORTS.includes(transport)) {
+        throw new Error(`Invalid transport "${transport}". Allowed: ${TRANSPORTS.join(", ")}`);
+    }
+    const rawPort = readOption(argv, "--port") ?? env.MCP_PORT ?? "3000";
+    const port = Number(rawPort);
+    if (rawPort.trim() === "" || !Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`Invalid port "${rawPort}": expected an integer between 0 and 65535`);
+    }
+    const host = readOption(argv, "--host") ?? env.MCP_HOST ?? "127.0.0.1";
+    const allowedHosts = (env.MCP_ALLOWED_HOSTS ?? "").split(",").map(value => value.trim()).filter(Boolean);
+    return { transport: transport, host, port, allowedHosts };
+}
+//# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,GAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAEtD,sFAAsF;AACtF,SAAS,UAAU,CAAC,IAAc,EAAE,IAAY;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAC;YAC9C,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAc,EAAE,GAAsB;IAChE,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC;IAClF,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAA0B,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,sBAAsB,SAAS,eAAe,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,MAAM,CAAC;IACrE,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACjF,MAAM,IAAI,KAAK,CAAC,iBAAiB,OAAO,4CAA4C,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,WAAW,CAAC;IACvE,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEzG,OAAO,EAAE,SAAS,EAAE,SAA0B,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;AAC7E,CAAC"}

package/build/format.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Formats search results for the MCP text output. Pure helper (no network).
+ * Results are numbered; `note` entries (e.g. empty content index) are appended unnumbered.
+ */
+export declare function formatSearchResults(results: any[]): string;
+//# sourceMappingURL=format.d.ts.map

package/build/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,MAAM,CAmB1D"}

package/build/format.js

@@ -0,0 +1,23 @@
+/**
+ * Formats search results for the MCP text output. Pure helper (no network).
+ * Results are numbered; `note` entries (e.g. empty content index) are appended unnumbered.
+ */
+export function formatSearchResults(results) {
+    if (results.length === 0) {
+        return "No results found.";
+    }
+    const notes = results.filter((result) => result.type === "note");
+    const items = results.filter((result) => result.type !== "note");
+    const numbered = items.map((result, index) => `${index + 1}. **${result.title}**
+   Type: ${result.type}
+   URL: ${result.url}
+   Description: ${result.description || "No description available"}
+
+`);
+    const trailing = notes.map((note) => `**${note.title}**
+   ${note.description}
+
+`);
+    return [...numbered, ...trailing].join("\n");
+}
+//# sourceMappingURL=format.js.map

package/build/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAc;IAChD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IAEjE,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,KAAK;WACpE,MAAM,CAAC,IAAI;UACZ,MAAM,CAAC,GAAG;kBACF,MAAM,CAAC,WAAW,IAAI,0BAA0B;;CAEjE,CAAC,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK;KACjD,IAAI,CAAC,WAAW;;CAEpB,CAAC,CAAC;IACD,OAAO,CAAC,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC"}

package/build/http-server.d.ts

@@ -0,0 +1,15 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export interface HttpServerOptions {
+    host: string;
+    port: number;
+    createServer: () => Server;
+    allowedHosts?: string[];
+}
+export interface RunningHttpServer {
+    port: number;
+    /** Address actually bound, as `ip:port` (`[ip]:port` for IPv6), not the configured host name. */
+    address: string;
+    close(): Promise<void>;
+}
+export declare function startHttpServer(options: HttpServerOptions): Promise<RunningHttpServer>;
+//# sourceMappingURL=http-server.d.ts.map

package/build/http-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAMxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAkCD,wBAAsB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsG5F"}

package/build/http-server.js

@@ -0,0 +1,131 @@
+import { createServer as createHttpServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+const MAX_BODY_BYTES = 1024 * 1024;
+const CLOSE_GRACE_MS = 2000;
+function sendJson(res, status, body, headers = {}) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(payload), ...headers });
+    res.end(payload);
+}
+const rpcError = (code, message) => ({ jsonrpc: "2.0", error: { code, message }, id: null });
+/** Reads the body, giving up as soon as it exceeds the limit. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const declared = Number(req.headers["content-length"]);
+        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+            resolve(null);
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                chunks.length = 0;
+                resolve(null);
+                return;
+            }
+            if (size <= MAX_BODY_BYTES)
+                chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+export async function startHttpServer(options) {
+    const extraHosts = new Set(options.allowedHosts ?? []);
+    let allowed = new Set();
+    const handle = async (req, res) => {
+        // DNS rebinding: the Host header must be a known loopback name (or explicitly allowed)
+        const host = req.headers.host ?? "";
+        if (!allowed.has(host)) {
+            sendJson(res, 403, rpcError(-32000, "Forbidden: invalid Host header"));
+            return;
+        }
+        const path = new URL(req.url ?? "/", "http://localhost").pathname;
+        if (path === "/healthz" && req.method === "GET") {
+            res.writeHead(200, { "content-type": "text/plain" });
+            res.end("ok");
+            return;
+        }
+        const origin = req.headers.origin;
+        if (origin !== undefined) {
+            let originHost = "";
+            try {
+                originHost = new URL(origin).host;
+            }
+            catch {
+                // an unparsable Origin ("null", garbage) is rejected below
+            }
+            if (!allowed.has(originHost)) {
+                sendJson(res, 403, rpcError(-32000, "Forbidden: invalid Origin header"));
+                return;
+            }
+        }
+        if (path !== "/mcp") {
+            sendJson(res, 404, rpcError(-32000, "Not found"));
+            return;
+        }
+        if (req.method !== "POST") {
+            sendJson(res, 405, rpcError(-32000, "Method not allowed"), { allow: "POST" });
+            return;
+        }
+        if (!/^application\/json\b/i.test(req.headers["content-type"] ?? "")) {
+            sendJson(res, 415, rpcError(-32000, "Content-Type must be application/json"));
+            return;
+        }
+        const raw = await readBody(req);
+        if (raw === null) {
+            sendJson(res, 413, rpcError(-32000, "Request body too large (max 1 MiB)"), { connection: "close" });
+            return;
+        }
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            sendJson(res, 400, rpcError(-32700, "Parse error"));
+            return;
+        }
+        // Stateless: one MCP server and transport per request, shared services live in createServer's closure
+        const mcp = options.createServer();
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+            void mcp.close().catch(() => { });
+        });
+        await mcp.connect(transport);
+        await transport.handleRequest(req, res, body);
+    };
+    const server = createHttpServer((req, res) => {
+        handle(req, res).catch((error) => {
+            console.error("💥 HTTP request failed:", error instanceof Error ? error.message : error);
+            if (!res.headersSent)
+                sendJson(res, 500, rpcError(-32603, "Internal server error"));
+            else
+                res.end();
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : options.port;
+    allowed = new Set([`localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`, ...extraHosts]);
+    const bound = typeof address === "object" && address
+        ? `${address.family === "IPv6" ? `[${address.address}]` : address.address}:${address.port}`
+        : `${options.host}:${port}`;
+    return {
+        port,
+        address: bound,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeIdleConnections();
+            setTimeout(() => server.closeAllConnections(), CLOSE_GRACE_MS).unref();
+        }),
+    };
+}
+//# sourceMappingURL=http-server.js.map

package/build/http-server.js.map

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