deepwiki-mcp-slim 0.0.0-stage → 0.1.3

package/README.md

@@ -1,3 +1,254 @@
-# Temporary Holding Version
+# DeepWiki MCP Slim
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, unofficial [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) proxy for [DeepWiki](https://deepwiki.com/). It exposes the three public DeepWiki wiki tools while removing instructions about unavailable private-mode and Devin tools.
+
+**Keep the useful DeepWiki instructions, without advertising tools the agent cannot use.**
+
+## Why this exists
+
+DeepWiki's public MCP endpoint exposes three wiki tools, but its server initialization instructions can mention additional tools that are not available through that endpoint. Coding agents may receive those instructions even though the tools are absent from their tool list.
+
+This proxy gives an MCP client a smaller, consistent view:
+
+| | Direct DeepWiki | DeepWiki MCP Slim |
+| --- | --- | --- |
+| Public wiki tools | 3 | Same 3 |
+| General DeepWiki instructions | Included | Preserved |
+| `devin_*` references | May be included | Removed |
+| `list_wiki_repos` and `generate_wiki` references | May be included | Removed |
+| Tool arguments and responses | From DeepWiki | Forwarded unchanged |
+
+The proxy **does not run DeepWiki locally**. It connects to `https://mcp.deepwiki.com/mcp` for every local MCP server process.
+
+## How it works
+
+```text
+Coding agent (OpenCode / Claude Code / OMP / another MCP client)
+       |
+       | MCP over stdio
+       v
+deepwiki-mcp-slim (local Node.js process)
+       |   - allowlist public tools
+       |   - filter initialization instructions
+       |   - forward tool calls and responses
+       |
+       | MCP over Streamable HTTP
+       v
+https://mcp.deepwiki.com/mcp
+```
+
+On startup, the proxy connects to DeepWiki, reads its initialization instructions, removes lines referring to unavailable tools, and advertises the remaining instructions to the local MCP client. It then forwards requests for these three tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `ask_wiki_question` | Ask a question about a repository |
+| `read_wiki_contents` | Read repository wiki content |
+| `read_wiki_structure` | Explore the structure of a repository's wiki |
+
+The filter currently removes any instruction **line** containing a `devin_*` name, `list_wiki_repos`, or `generate_wiki`. It also removes the observed Devin OAuth/organization preface because that line refers to `devin_*`.
+
+This is a **fixed tool allowlist**, not automatic discovery of all future public DeepWiki tools.
+
+## Requirements
+
+- Node.js **20 or newer** and npm
+- Network access to `https://mcp.deepwiki.com/mcp`
+- An MCP client that can launch a **stdio** server
+
+No DeepWiki API key is required for the public endpoint used by this project. This proxy does not implement private-mode or upstream OAuth authentication.
+
+## Installation
+
+**After the package is first published to npm**, you do not need to clone this repository on each machine. Choose one of the following approaches.
+
+### Option A: Global install
+
+Recommended when you prefer quick, predictable startup:
+
+```bash
+npm install -g deepwiki-mcp-slim
+deepwiki-mcp-slim
+```
+
+The command starts a stdio MCP server and waits for a client to connect. **It is normal for it to print nothing**; stop it with Ctrl+C if you launched it manually. In your harness configuration, use the command `deepwiki-mcp-slim` without launching it yourself.
+
+Upgrade intentionally with:
+
+```bash
+npm install -g deepwiki-mcp-slim@latest
+```
+
+### Option B: Run with npx
+
+No global install or clone required:
+
+```bash
+npx -y deepwiki-mcp-slim@0.1.3
+```
+
+This installs the requested package into npm's cache when needed, then starts the MCP server. Use that command in the harness configuration instead of running it manually.
+
+**Version pinning is recommended for coding agents.** Without the explicit `@0.1.3` version, a later launch can resolve a newer release unexpectedly. `-y` disables npm's install confirmation prompt, so use it only for a package you trust.
+
+| | Global install | npx with pinned version |
+| --- | --- | --- |
+| One-time installation | Required on each machine | Not required |
+| Launch overhead | Lower | npm startup and package resolution/cache checks |
+| Offline reliability | Installed command works; DeepWiki still needs network | Also requires the package to be present in the npm cache |
+| Updates | You choose when to reinstall | You choose when to change the version in config |
+| Best fit | Frequently launched local agents | Shared, portable MCP configurations |
+
+Neither method removes the proxy's requirement to contact DeepWiki's upstream HTTPS service. The package must be available on npm before either of these commands will work.
+
+### Install from source (development)
+
+```bash
+git clone https://github.com/capyBearista/deepwiki-mcp-slim.git
+cd deepwiki-mcp-slim
+npm ci
+npm test
+npm link
+```
+
+`npm link` makes the local checkout's executable available to harnesses using the same Node/npm installation.
+
+### Notes on environments
+
+Node.js 20+ and npm must be installed in **each environment where your coding harness runs** (for example, native Windows and WSL are separate environments). Ensure the harness can find `npx` or `deepwiki-mcp-slim` on its `PATH`. You can inspect the resolved command with `command -v` on Linux/macOS or `where.exe` on Windows.
+
+If a source checkout reports `spawn deepwiki-mcp-slim EACCES` on Linux, check the executable bit:
+
+```bash
+ls -l src/index.mjs
+chmod +x src/index.mjs
+```
+
+The repository tracks `src/index.mjs` as executable. Published npm CLI binaries receive npm's platform-specific executable linking/shims.
+
+## Configure a coding harness
+
+Configure **`deepwiki-mcp-slim` as a local/stdio server named `deepwiki`**. Replace any existing DeepWiki connection rather than registering both, or your agent may still receive the unfiltered server instructions.
+
+For **npx** instead of a global install, replace the command with `["npx", "-y", "deepwiki-mcp-slim@0.1.3"]` in OpenCode, or use `"command": "npx", "args": ["-y", "deepwiki-mcp-slim@0.1.3"]` in other stdio MCP clients. In either case, make sure the harness can find the executable on `PATH`.
+
+### OpenCode V2
+
+In `opencode.jsonc`, replace the `deepwiki` entry under **`mcp.servers`**:
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "deepwiki": {
+        "type": "local",
+        "command": ["deepwiki-mcp-slim"]
+      }
+    }
+  }
+}
+```
+
+Merge this into your existing configuration; do not replace unrelated MCP servers. Retaining the `deepwiki` server name also preserves references to that server in agent-specific MCP assignments.
+
+See the [OpenCode V2 MCP documentation](https://opencode.ai/v2/docs/mcp-servers).
+
+### Claude Code (including plugins)
+
+For a regular MCP configuration or a plugin's `.mcp.json`, replace the existing `deepwiki` entry:
+
+```json
+{
+  "mcpServers": {
+    "deepwiki": {
+      "type": "stdio",
+      "command": "deepwiki-mcp-slim",
+      "args": []
+    }
+  }
+}
+```
+
+If DeepWiki is supplied by a **Claude Code plugin**, change the plugin's own `.mcp.json`; editing an unrelated user-level MCP entry won't replace the plugin-bundled server. Each machine running the plugin must also have the executable installed. Repository tests or validation scripts that require all MCPs to be HTTP must be updated to permit this stdio server.
+
+See [Claude Code documentation](https://code.claude.com/docs/).
+
+### Oh My Pi (OMP)
+
+In `~/.omp/agent/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "deepwiki": {
+      "type": "stdio",
+      "command": "deepwiki-mcp-slim",
+      "args": []
+    }
+  }
+}
+```
+
+OMP also supports `instructions: false` on a direct HTTP DeepWiki connection, **but that removes all server instructions**, not just the irrelevant ones. Use this proxy if you want to retain the useful instructions. Check `/mcp list` to ensure OMP selected the intended server when multiple configuration sources exist.
+
+See [OMP MCP configuration](https://github.com/can1357/oh-my-pi/blob/main/docs/mcp-config.md).
+
+### Other environments
+
+Any MCP client supporting local stdio servers can launch the same executable. The essential settings are:
+
+- **Transport:** stdio
+- **Command:** `deepwiki-mcp-slim`
+- **Server name:** `deepwiki` (recommended for compatibility)
+
+No always-running daemon or separate HTTP port is needed. The coding harness starts and stops its own local proxy process.
+
+## Verification
+
+First, run the unit tests:
+
+```bash
+npm test
+```
+
+These test the instruction filter only. To inspect the running MCP server:
+
+```bash
+npx @modelcontextprotocol/inspector deepwiki-mcp-slim
+```
+
+Connect through the Inspector and check:
+
+1. `tools/list` contains exactly `ask_wiki_question`, `read_wiki_contents`, and `read_wiki_structure`.
+2. Server initialization instructions still contain useful wiki guidance, with no `devin_*`, `list_wiki_repos`, or `generate_wiki` references.
+3. Calling one public wiki tool returns a response from DeepWiki.
+
+**The live end-to-end behavior has not been verified by the repository's unit tests.** The Inspector check is an integration test you should run after installation.
+
+## Limitations
+
+- **Tools only:** MCP prompts, resources, server-to-client notifications, cancellation, and upstream authentication are not transparently proxied.
+- **Text-based filter:** The filter removes matching instruction lines, not semantic paragraphs. If DeepWiki changes its instruction format, irrelevant text could remain or a useful matching line could be removed.
+- **Fixed allowlist:** New DeepWiki tools will not appear automatically. Review and explicitly add them when appropriate.
+- **Upstream dependency:** Connection and tool execution depend on the availability and behavior of DeepWiki's public MCP endpoint.
+- **Not an access-control boundary:** This project removes unwanted tool exposure and guidance; it does not sandbox or verify content returned by DeepWiki.
+
+## Development
+
+```bash
+npm ci
+npm test
+node --check src/index.mjs
+```
+
+The local MCP server reads its version from `package.json` instead of a separate hardcoded value.
+
+| File | Responsibility |
+| --- | --- |
+| `src/index.mjs` | Connects to DeepWiki, registers the local MCP server, and forwards allowlisted tools |
+| `src/filter-instructions.mjs` | Filters unavailable-tool instructions |
+| `test/filter-instructions.test.mjs` | Regression tests for instruction filtering |
+| `test/package.test.mjs` | Checks npm package metadata and the CLI entrypoint |
+
+The executable uses stdout for the MCP JSON-RPC protocol. If you add diagnostic logging, send it to **stderr**, never stdout.
+
+This project is not affiliated with DeepWiki or Devin.

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "deepwiki-mcp-slim",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "DeepWiki MCP proxy that preserves public wiki instructions and filters unavailable tools.",
+  "keywords": [
+    "deepwiki",
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "mcp-proxy",
+    "ai-agents",
+    "claude-code",
+    "opencode",
+    "oh-my-pi"
+  ],
+  "type": "module",
+  "bin": {
+    "deepwiki-mcp-slim": "./src/index.mjs"
+  },
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/capyBearista/deepwiki-mcp-slim.git"
+  },
+  "homepage": "https://github.com/capyBearista/deepwiki-mcp-slim#readme",
+  "bugs": {
+    "url": "https://github.com/capyBearista/deepwiki-mcp-slim/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "2.4.0",
+    "@modelcontextprotocol/server": "2.4.0"
+  }
+}

package/src/filter-instructions.mjs

@@ -0,0 +1,15 @@
+// Retain DeepWiki guidance while omitting tools unavailable through its public MCP.
+// The observed server instructions contain one line per tool, plus a Devin-only
+// organization/OAuth preface mentioning devin_*.
+const UNAVAILABLE_TOOL = /(?:^|[^\w])(?:devin_(?:\*|[a-z0-9_]+)|list_wiki_repos|generate_wiki)(?!\w)/i;
+
+export function filterUnavailableToolInstructions(instructions) {
+  if (!instructions) return undefined;
+  const filtered = instructions
+    .split(/\r?\n/)
+    .filter((line) => !UNAVAILABLE_TOOL.test(line))
+    .join("\n")
+    .replace(/\n(?:[ \t]*\n){2,}/g, "\n\n")
+    .trim();
+  return filtered || undefined;
+}

package/src/index.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { filterUnavailableToolInstructions } from "./filter-instructions.mjs";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+const allowed = new Set([
+  "ask_wiki_question",
+  "read_wiki_contents",
+  "read_wiki_structure",
+]);
+
+// Preserve DeepWiki instructions, excluding guidance for unavailable tools.
+const upstream = new Client({ name: "deepwiki-mcp-slim", version });
+await upstream.connect(
+  new StreamableHTTPClientTransport(new URL("https://mcp.deepwiki.com/mcp")),
+);
+
+// Forward the selectively filtered upstream instructions during initialization.
+const instructions = filterUnavailableToolInstructions(upstream.getInstructions());
+const mcp = new McpServer(
+  { name: "deepwiki-mcp-slim", version },
+  { instructions },
+);
+// Use the documented underlying protocol server for precise tool forwarding.
+const server = mcp.server;
+server.registerCapabilities({ tools: {} });
+
+server.setRequestHandler("tools/list", async () => {
+  const { tools } = await upstream.listTools();
+  return { tools: tools.filter((tool) => allowed.has(tool.name)) };
+});
+
+server.setRequestHandler("tools/call", async ({ params }) => {
+  if (!allowed.has(params.name)) {
+    throw new Error(`Tool not exposed: ${params.name}`);
+  }
+  return upstream.callTool({
+    name: params.name,
+    arguments: params.arguments ?? {},
+  });
+});
+
+await server.connect(new StdioServerTransport());
+server.onclose = () => { void upstream.close(); };