@aistoragedepot/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIStorageDepot
+
+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,59 @@
+# @aistoragedepot/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **your
+[AIStorageDepot](https://www.aistoragedepot.com) library** to any MCP-aware AI client —
+Claude Desktop, Cursor, Cline, Windsurf, and others.
+
+Your stored content shows up where you actually work:
+
+- **Prompts** → your prompt-format items become MCP prompts (slash-commands), with each
+  `[field]` surfaced as a prompt argument you fill in.
+- **Resources** → every item (rules, docs, skills, MCP configs, prompts) is readable at
+  `aisd://item/<id>`, so an agent can pull "my coding rules" or "my project guidelines"
+  into context on demand.
+- **Tools** → `search_library(query)` and `get_item(id)` let an agent find and fetch
+  anything in your library programmatically.
+
+## Setup
+
+1. In AIStorageDepot (a **PLUS** plan is required for API tokens), go to **Settings → API
+   tokens** and create a token. Copy it.
+2. Add the server to your MCP client's config. Example (Claude Desktop /
+   `claude_desktop_config.json`, Cursor `~/.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "aistoragedepot": {
+      "command": "npx",
+      "args": ["-y", "@aistoragedepot/mcp"],
+      "env": {
+        "AISD_TOKEN": "aisd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+3. Restart the client. Your prompts appear as slash-commands; your items are available as
+   resources; and the `search_library` / `get_item` tools are ready.
+
+## Configuration
+
+| Env var | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `AISD_TOKEN` | yes | — | Token from Settings → API tokens. Has full access to your account — keep it secret. |
+| `AISD_BASE_URL` | no | `https://www.aistoragedepot.com` | Point at a self-hosted / dev instance if needed. |
+
+## Notes
+
+- Read-only in v0.1 (it surfaces and fetches your content; it doesn't write back).
+- The library snapshot is cached for ~30s, so a burst of calls hits the API once.
+- Revoke a token any time in Settings → API tokens; the server loses access immediately.
+
+## Local development
+
+```bash
+npm install
+AISD_TOKEN=<token> AISD_BASE_URL=http://localhost:3100 npm run test:client
+```

package/index.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// AIStorageDepot MCP server.
+//
+// Exposes the signed-in user's library to any MCP-aware AI client (Claude Desktop,
+// Cursor, Cline, Windsurf, …) over stdio:
+//   • Prompts   — prompt-format items, with their [fields] surfaced as prompt arguments.
+//   • Resources — every item (rules, docs, skills, configs, prompts) readable by URI.
+//   • Tools     — search_library(query) and get_item(id).
+//
+// Auth + target are configured via env:
+//   AISD_TOKEN     (required)  a token from AIStorageDepot → Settings → API tokens.
+//   AISD_BASE_URL  (optional)  defaults to https://www.aistoragedepot.com.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const BASE_URL = (process.env.AISD_BASE_URL || "https://www.aistoragedepot.com").replace(/\/+$/, "");
+const TOKEN = process.env.AISD_TOKEN;
+
+if (!TOKEN) {
+  console.error("AISD_TOKEN is required. Create one in AIStorageDepot → Settings → API tokens.");
+  process.exit(1);
+}
+
+async function api(path) {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    headers: { Authorization: `Bearer ${TOKEN}`, Accept: "application/json" },
+  });
+  if (res.status === 401) throw new Error("AIStorageDepot rejected the token (401) — check AISD_TOKEN.");
+  if (!res.ok) throw new Error(`AIStorageDepot ${path} → HTTP ${res.status}`);
+  return res.json();
+}
+
+// Library snapshot, cached briefly so a burst of list/read calls hits the API once.
+let cache = { at: 0, workspaces: [], items: [] };
+async function snapshot() {
+  if (cache.items.length && Date.now() - cache.at < 30_000) return cache;
+  const workspaces = await api("/api/workspaces");
+  const items = [];
+  for (const ws of workspaces) {
+    try {
+      const lib = await api(`/api/library?workspace=${encodeURIComponent(ws.id)}`);
+      for (const it of lib.items || []) items.push(it);
+    } catch {
+      // a workspace we can't read (or that errored) — skip it, keep the rest.
+    }
+  }
+  cache = { at: Date.now(), workspaces, items };
+  return cache;
+}
+
+// --- mapping helpers ---
+const slug = (s) =>
+  String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48) || "item";
+const isPrompt = (it) => it.type?.format === "prompt" || (it.placeholders?.length ?? 0) > 0;
+const mimeFor = (it) => (it.type?.format === "json" ? "application/json" : "text/markdown");
+
+// Stable, unique prompt name per item (slug of the title, deduped with an id suffix).
+// Rebuilt deterministically from the snapshot so ListPrompts and GetPrompt agree.
+function promptIndex(items) {
+  const used = new Set();
+  const byName = new Map();
+  for (const it of items.filter(isPrompt)) {
+    let name = slug(it.title);
+    if (used.has(name)) name = `${name}-${it.id.slice(-4)}`;
+    used.add(name);
+    byName.set(name, it);
+  }
+  return byName;
+}
+
+// MCP argument names should be simple identifiers; map them back to the original
+// "[placeholder]" text so we can substitute into the body.
+function argMap(placeholders) {
+  const m = new Map();
+  const used = new Set();
+  for (const p of placeholders || []) {
+    let a = slug(p).replace(/-/g, "_");
+    while (used.has(a)) a += "_";
+    used.add(a);
+    m.set(a, p);
+  }
+  return m;
+}
+
+function fillBody(body, placeholders, args) {
+  let out = body;
+  for (const [argName, original] of argMap(placeholders)) {
+    const val = args?.[argName];
+    if (val != null && val !== "") out = out.split(`[${original}]`).join(val);
+  }
+  return out;
+}
+
+const server = new Server(
+  { name: "aistoragedepot", version: "0.1.0" },
+  { capabilities: { resources: {}, prompts: {}, tools: {} } },
+);
+
+// ---- Resources: every item, readable at aisd://item/<id> ----
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const { items } = await snapshot();
+  return {
+    resources: items.map((it) => ({
+      uri: `aisd://item/${it.id}`,
+      name: it.title,
+      description: `${it.type?.name || "Item"}${it.tags?.length ? " · " + it.tags.join(", ") : ""}`,
+      mimeType: mimeFor(it),
+    })),
+  };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  const { uri } = req.params;
+  const id = uri.replace(/^aisd:\/\/item\//, "");
+  const { items } = await snapshot();
+  const it = items.find((x) => x.id === id);
+  if (!it) throw new Error(`Unknown resource: ${uri}`);
+  return { contents: [{ uri, mimeType: mimeFor(it), text: it.body }] };
+});
+
+// ---- Prompts: prompt-format items, [fields] → arguments ----
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  const { items } = await snapshot();
+  const prompts = [];
+  for (const [name, it] of promptIndex(items)) {
+    const am = argMap(it.placeholders);
+    prompts.push({
+      name,
+      description: `${it.type?.name || "Prompt"}: “${it.title}” (AIStorageDepot)`,
+      arguments: [...am.keys()].map((a) => ({
+        name: a,
+        description: `Value for [${am.get(a)}]`,
+        required: false,
+      })),
+    });
+  }
+  return { prompts };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+  const { items } = await snapshot();
+  const it = promptIndex(items).get(req.params.name);
+  if (!it) throw new Error(`Unknown prompt: ${req.params.name}`);
+  const text = fillBody(it.body, it.placeholders, req.params.arguments || {});
+  return {
+    description: it.title,
+    messages: [{ role: "user", content: { type: "text", text } }],
+  };
+});
+
+// ---- Tools: search + fetch ----
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "search_library",
+      description:
+        "Search your AIStorageDepot library (prompts, rules, docs, skills, configs) by keyword across titles, bodies, tags, and categories. Returns matching items with their aisd://item/<id> resource URIs.",
+      inputSchema: {
+        type: "object",
+        properties: { query: { type: "string", description: "Keyword(s) to search for." } },
+        required: ["query"],
+      },
+    },
+    {
+      name: "get_item",
+      description:
+        "Fetch the full content of one library item by its id or aisd://item/<id> URI (e.g. from a search_library result).",
+      inputSchema: {
+        type: "object",
+        properties: { id: { type: "string", description: "The item id, or an aisd://item/<id> URI." } },
+        required: ["id"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    if (name === "search_library") {
+      const q = String(args?.query || "").trim();
+      if (q.length < 2) return { content: [{ type: "text", text: "Enter at least 2 characters." }] };
+      const { workspaces } = await snapshot();
+      const ids = workspaces.map((w) => w.id).join(",");
+      const results = await api(`/api/search?q=${encodeURIComponent(q)}&workspaces=${encodeURIComponent(ids)}`);
+      if (!results.length) return { content: [{ type: "text", text: `No matches for “${q}”.` }] };
+      const lines = results.map(
+        (r) => `• ${r.title} — ${r.typeName} (in ${r.workspaceName})  →  aisd://item/${r.id}`,
+      );
+      return { content: [{ type: "text", text: `${results.length} match(es) for “${q}”:\n${lines.join("\n")}` }] };
+    }
+    if (name === "get_item") {
+      const id = String(args?.id || "").replace(/^aisd:\/\/item\//, "");
+      const { items } = await snapshot();
+      const it = items.find((x) => x.id === id);
+      if (!it) return { content: [{ type: "text", text: `No item with id ${id}.` }], isError: true };
+      return { content: [{ type: "text", text: it.body }] };
+    }
+    return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+  } catch (err) {
+    return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`AIStorageDepot MCP server connected → ${BASE_URL}`);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@aistoragedepot/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for your AIStorageDepot library — exposes your prompts, rules, docs, and skills to MCP-aware AI clients (Claude, Cursor, Cline, …).",
+  "type": "module",
+  "bin": {
+    "aistoragedepot-mcp": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test:client": "node test-client.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "model-context-protocol",
+    "aistoragedepot",
+    "prompts",
+    "ai",
+    "llm",
+    "claude",
+    "cursor"
+  ],
+  "author": "AIStorageDepot",
+  "homepage": "https://www.aistoragedepot.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidmcolvin/aistoragedepot-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/davidmcolvin/aistoragedepot-mcp/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}