@xyd-js/mcp 0.0.0-build-9f87f13-20250930210637

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) LiveSession Sp.z.o.o
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+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

@@ -0,0 +1,89 @@
+# @xyd-js/mcp
+
+Utilities for building Model Context Protocol (MCP) servers in the xyd ecosystem.
+
+This package exposes helpers to:
+
+- Register API Reference resources (as Markdown) derived from a Uniform source
+- Register callable MCP tools from OpenAPI or GraphQL specs with structured input schemas
+
+Currently supported Uniform sources:
+
+- OpenAPI: `.json`, `.yaml`, `.yml`
+- GraphQL schema files: `.graphql`, `.graphqls`
+
+Typescript/React sources are not supported yet.
+
+## Installation
+
+```bash
+bun add @xyd-js/mcp
+```
+
+Peer/runtime requirements: Bun or Node.js compatible ESM environment.
+
+## API
+
+```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { mcpUniformResources, mcpUniformTools } from "@xyd-js/mcp";
+
+const server = new McpServer({ name: "xyd-mcp", version: "0.1.0" });
+
+// Path to a Uniform source (OpenAPI JSON/YAML or GraphQL schema)
+const uniformSource = "./openapi.json";
+
+// Register API reference resources (text/markdown) under uri: api-reference://<canonical>
+await mcpUniformResources(server, uniformSource);
+
+// Register tools; if your API needs auth, pass a token which will be sent
+// as Authorization: Bearer <token> for outgoing requests
+await mcpUniformTools(server, uniformSource, process.env.API_TOKEN || "");
+```
+
+### `mcpUniformResources(server, uniformSource)`
+
+Generates Markdown API reference pages from the provided Uniform source and registers them as MCP resources using `api-reference://<canonical>` URIs with `mimeType: text/markdown`.
+
+### `mcpUniformTools(server, uniformSource, token)`
+
+Creates MCP tools for each operation discovered in the Uniform source. Tool input schemas are derived from the API definition and grouped by:
+
+- `pathParams`
+- `queryParams`
+- `headers`
+- `requestBody`
+
+When a tool is invoked it will:
+
+- Perform a fetch using the operation method and URL
+- Include `Authorization: Bearer <token>` if a token was provided
+- Return both a `resource_link` to the associated API reference and the JSON response (as text)
+
+## Uniform Source Detection
+
+`uniformSource` can be any of:
+
+- OpenAPI spec: `.json`, `.yaml`, `.yml`
+- GraphQL schema: `.graphql`, `.graphqls`
+
+If the extension cannot be detected or the source cannot be loaded, no tools/resources will be registered.
+
+## Example
+
+```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { mcpUniformResources, mcpUniformTools } from "@xyd-js/mcp";
+
+const server = new McpServer({ name: "example", version: "0.0.0" });
+await mcpUniformResources(server, "./demo/simple/openapi.json");
+await mcpUniformTools(server, "./demo/simple/openapi.json", "my-access-token");
+```
+
+## Notes
+
+- Responses are currently assumed to be JSON when returning tool results.
+- Markdown rendering uses xyd components highlighting where possible.
+- This library is ESM-only.
+
+