@thotyo/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thotyo
+
+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,87 @@
+# Thotyo MCP Server
+
+Thotyo is a machine-facing documentation infrastructure for AI agents. This MCP (Model Context Protocol) server acts as an adapter to access Thotyo's canonical, versioned documentation via a simple tool interface.
+
+## Installation
+
+### Global Installation
+```bash
+npm install -g @thotyo/mcp
+```
+
+### Usage with npx
+```bash
+npx @thotyo/mcp
+```
+
+## Configuration
+
+The server requires an API key from Thotyo to function.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `THOTYO_API_KEY` | **Required**. Your Thotyo API key. | None |
+| `THOTYO_API_BASE_URL` | Base URL of the Thotyo API. | `https://www.thotyo.com` |
+
+## Integration
+
+### Gemini CLI
+
+To use this server with the Gemini CLI, add it to your `mcpServers` configuration (usually in `~/.gemini/config.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "thotyo": {
+      "command": "npx",
+      "args": ["-y", "@thotyo/mcp"],
+      "env": {
+        "THOTYO_API_KEY": "your_api_key_here",
+        "THOTYO_API_BASE_URL": "https://www.thotyo.com"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot
+
+If your environment supports MCP (like some editor extensions), you can configure the Thotyo MCP server using the `stdio` transport.
+
+If GitHub Copilot does not yet natively support MCP in your specific IDE version, you can:
+1. Use an MCP-to-HTTP gateway.
+2. Use the Thotyo API directly via HTTP if your Copilot setup allows custom skills/extensions.
+3. Use a compatible MCP host that bridges to Copilot.
+
+## Tools
+
+### `get_symbol`
+Retrieve documentation for a specific symbol in a library version.
+
+**Arguments:**
+- `project` (string): The project or library name (e.g., 'node').
+- `version` (string): The version string (e.g., '22.0').
+- `symbol_id` (string): The unique identifier for the symbol (e.g., 'array-prototype-foreach').
+
+### `resolve_symbol`
+Resolve a free-text query to a canonical `symbol_id` for a library version.
+
+**Arguments:**
+- `query` (string): The free-text query (e.g., 'foreach', 'array.map').
+- `project` (string): The project or library name (e.g., 'node').
+- `version` (string): The version string (e.g., '22.0').
+- `limit` (number, optional): Optional limit for number of candidates (default 5, max 10).
+
+## Error Handling
+
+The server returns structured error objects:
+- `{ error: "missing_api_key" }`: API key not provided.
+- `{ error: "unauthorized" }`: Invalid API key.
+- `{ error: "rate_limited" }`: Too many requests.
+- `{ error: "not_found" }`: Symbol or project not found.
+- `{ error: "upstream_error" }`: Other errors from the Thotyo API.
+
+## License
+MIT

package/dist/server.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { fetchSymbol, resolveSymbol } from "./thotyoClient.js";
+const server = new Server({
+    name: "thotyo-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "get_symbol",
+                description: "Retrieve documentation for a specific symbol in a library version",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: {
+                            type: "string",
+                            description: "The project or library name (e.g., 'node')",
+                        },
+                        version: {
+                            type: "string",
+                            description: "The version string (e.g., '22.0')",
+                        },
+                        symbol_id: {
+                            type: "string",
+                            description: "The unique identifier for the symbol (e.g., 'array-prototype-foreach')",
+                        },
+                    },
+                    required: ["project", "version", "symbol_id"],
+                },
+            },
+            {
+                name: "resolve_symbol",
+                description: "Resolve a free-text query to a canonical symbol_id for a library version",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "The free-text query (e.g., 'foreach', 'array.map')",
+                        },
+                        project: {
+                            type: "string",
+                            description: "The project or library name (e.g., 'node')",
+                        },
+                        version: {
+                            type: "string",
+                            description: "The version string (e.g., '22.0')",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Optional limit for number of candidates (default 5, max 10)",
+                        },
+                    },
+                    required: ["query", "project", "version"],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === "get_symbol") {
+        const args = request.params.arguments;
+        const schema = z.object({
+            project: z.string(),
+            version: z.string(),
+            symbol_id: z.string(),
+        });
+        const parseResult = schema.safeParse(args);
+        if (!parseResult.success) {
+            throw new Error(`Invalid arguments: ${parseResult.error.message}`);
+        }
+        const { project, version, symbol_id } = parseResult.data;
+        const result = await fetchSymbol(project, version, symbol_id);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: "error" in result && result.error !== undefined,
+        };
+    }
+    if (request.params.name === "resolve_symbol") {
+        const args = request.params.arguments;
+        const schema = z.object({
+            query: z.string(),
+            project: z.string(),
+            version: z.string(),
+            limit: z.number().optional(),
+        });
+        const parseResult = schema.safeParse(args);
+        if (!parseResult.success) {
+            throw new Error(`Invalid arguments: ${parseResult.error.message}`);
+        }
+        const { query, project, version, limit } = parseResult.data;
+        const result = await resolveSymbol(query, project, version, limit);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+            isError: "error" in result && result.error !== undefined,
+        };
+    }
+    throw new Error(`Tool not found: ${request.params.name}`);
+});
+async function run() {
+    if (!process.env.THOTYO_API_KEY) {
+        console.error("Warning: THOTYO_API_KEY environment variable is not set. Tool calls will return an error.");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Thotyo MCP Server running on STDIO");
+}
+run().catch((error) => {
+    console.error("Fatal error in main loop:", error);
+    process.exit(1);
+});

package/dist/thotyoClient.js

@@ -0,0 +1,54 @@
+const BASE_URL = process.env.THOTYO_API_BASE_URL || "https://www.thotyo.com";
+const API_KEY = process.env.THOTYO_API_KEY;
+async function request(path, params) {
+    if (!API_KEY) {
+        return { error: "missing_api_key" };
+    }
+    const url = `${BASE_URL}${path}${params ? `?${params.toString()}` : ""}`;
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                "Accept": "application/json",
+                "X-API-Key": API_KEY,
+            },
+        });
+        if (response.ok) {
+            return (await response.json());
+        }
+        if (response.status === 401 || response.status === 403) {
+            return { error: "unauthorized", status: response.status };
+        }
+        if (response.status === 429) {
+            return { error: "rate_limited", status: 429 };
+        }
+        if (response.status === 404) {
+            return { error: "not_found", status: 404 };
+        }
+        return {
+            error: "upstream_error",
+            status: response.status,
+            message: response.statusText,
+        };
+    }
+    catch (error) {
+        return {
+            error: "upstream_error",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function fetchSymbol(project, version, symbolId) {
+    return request(`/api/symbols/${encodeURIComponent(project)}/${encodeURIComponent(version)}/${encodeURIComponent(symbolId)}`);
+}
+export async function resolveSymbol(query, project, version, limit) {
+    const params = new URLSearchParams({
+        q: query,
+        project,
+        version,
+    });
+    if (limit) {
+        params.append("limit", limit.toString());
+    }
+    return request("/api/resolve", params);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@thotyo/mcp",
+  "version": "1.0.0",
+  "description": "Thotyo MCP server - Machine-facing documentation infrastructure for AI agents",
+  "type": "module",
+  "bin": {
+    "thotyo-mcp": "./dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/server.ts",
+    "build": "tsc && chmod +x dist/server.js",
+    "start": "node dist/server.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}