http-client-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# ACW Repo Reader (HTTP Client MCP Server)
+
+A Model Context Protocol (MCP) server that provides a set of tools to explore and read files from a repository. This is specifically designed to help AI agents understand and navigate large codebases.
+
+## Features
+
+- **read_api_spec**: Read the content of any file within the configured repository.
+- **list_directory**: List files and subdirectories.
+- **search_files**: Search for files across the entire repository using keywords.
+
+---
+
+## Quick Start (No Install)
+
+The easiest way to use this server is via `npx`. You can provide the target repository path as a command-line argument.
+
+### 1. Antigravity
+
+Add the following to your `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "http-client-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "http-client-mcp-server", "/absolute/path/to/your/target-repo"]
+    }
+  }
+}
+```
+
+### 2. Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "http-client-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "http-client-mcp-server", "/absolute/path/to/your/target-repo"]
+    }
+  }
+}
+```
+
+---
+
+## Manual Installation
+
+If you prefer to install it locally:
+
+### 1. Clone & Build
+
+```bash
+git clone https://github.com/noxhsxrk/http-client-mcp-server
+cd http-client-mcp-server
+npm install
+npm run build
+```
+
+### 2. Configuration
+
+You can point to the local `index.js` file:
+
+```json
+{
+  "mcpServers": {
+    "http-client-mcp-server": {
+      "command": "node",
+      "args": ["/path/to/http-client-mcp-server/index.js", "/path/to/your/target-repo"]
+    }
+  }
+}
+```
+
+---
+
+## Configuration Options
+
+You can specify the repository path in two ways:
+
+1. Command-line Argument: `http-client-mcp-server /path/to/repo` (Recommended)
+2. Environment Variable: Set `REPO_BASE_PATH=/path/to/repo`

package/index.js

@@ -0,0 +1,198 @@
+#!/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 fs from "node:fs/promises";
+import path from "node:path";
+const rawRepoPath = process.env.REPO_BASE_PATH || process.argv[2];
+if (!rawRepoPath) {
+    const currentPath = process.cwd();
+    console.error("Error: REPO_BASE_PATH environment variable or a command-line argument is required.");
+    console.error(`\nHint: If you want to use the current directory, the absolute path is:\n${currentPath}`);
+    console.error(`\nUsage example:\nacw-repo-reader ${currentPath}`);
+    console.error("\nTips to find your repository path:");
+    console.error("- macOS: Right-click folder + hold 'Option' key -> Select 'Copy as Pathname'");
+    console.error("- Windows: Shift + Right-click folder -> Select 'Copy as path'");
+    process.exit(1);
+}
+const REPO_BASE_PATH = path.resolve(rawRepoPath);
+const server = new Server({ name: "acw-repo-reader", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "read_api_spec",
+                description: "Reads API specifications, sequence diagrams, or any files from repository.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filepath: {
+                            type: "string",
+                            description: "Relative path to the file inside the repo",
+                        },
+                    },
+                    required: ["filepath"],
+                },
+            },
+            {
+                name: "list_directory",
+                description: "List files and folders in a specific directory inside repository. Use this to find the exact filename before reading.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        dirPath: {
+                            type: "string",
+                            description: "Relative directory path to list (e.g., '.' for root, or 'docs')",
+                        },
+                    },
+                    required: ["dirPath"],
+                },
+            },
+            {
+                name: "search_files",
+                description: "Search for files across the entire repository using a keyword (e.g., 'address', 'account'). Use this to find the exact filepath before reading.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        keyword: {
+                            type: "string",
+                            description: "Keyword to search for in filenames (e.g., 'update-address' or '.http')",
+                        },
+                    },
+                    required: ["keyword"],
+                },
+            },
+        ],
+    };
+});
+async function handleReadApiSpec(args) {
+    const filepath = typeof args?.filepath === "string" ? args.filepath : "";
+    if (!filepath) {
+        throw new Error("filepath is required and must be a string");
+    }
+    const fullPath = path.resolve(REPO_BASE_PATH, filepath);
+    if (!fullPath.startsWith(REPO_BASE_PATH)) {
+        console.error(`[Security Warning] Attempted path traversal: ${filepath}`);
+        throw new Error("Access denied: File is outside the repository base path.");
+    }
+    try {
+        const content = await fs.readFile(fullPath, "utf-8");
+        return {
+            content: [{ type: "text", text: content }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error reading file: ${error.message}` }],
+            isError: true,
+        };
+    }
+}
+async function handleListDirectory(args) {
+    const dirPath = typeof args?.dirPath === "string" ? args.dirPath : ".";
+    const fullDirPath = path.resolve(REPO_BASE_PATH, dirPath);
+    if (!fullDirPath.startsWith(REPO_BASE_PATH)) {
+        throw new Error("Access denied: Path is outside the repository base path.");
+    }
+    try {
+        const files = await fs.readdir(fullDirPath, { withFileTypes: true });
+        const fileList = files
+            .map((dirent) => `${dirent.isDirectory() ? "[DIR]" : "[FILE]"} ${dirent.name}`)
+            .join("\n");
+        return {
+            content: [{ type: "text", text: `Contents of ${dirPath}:\n${fileList}` }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error listing directory: ${error.message}` },
+            ],
+            isError: true,
+        };
+    }
+}
+async function findFilesRecursive(dir, keyword, basePath) {
+    let results = [];
+    const list = await fs.readdir(dir, { withFileTypes: true });
+    for (const file of list) {
+        if (file.isDirectory() &&
+            (file.name === "node_modules" ||
+                file.name === ".git" ||
+                file.name === ".idea" ||
+                file.name === ".vscode")) {
+            continue;
+        }
+        const fullPath = path.resolve(dir, file.name);
+        if (file.isDirectory()) {
+            const subResults = await findFilesRecursive(fullPath, keyword, basePath);
+            results = results.concat(subResults);
+        }
+        else if (file.name.toLowerCase().includes(keyword.toLowerCase())) {
+            results.push(path.relative(basePath, fullPath));
+        }
+    }
+    return results;
+}
+async function handleSearchFiles(args) {
+    const keyword = typeof args?.keyword === "string" ? args.keyword : "";
+    if (!keyword) {
+        throw new Error("keyword is required and must be a string");
+    }
+    try {
+        const matchedFiles = await findFilesRecursive(REPO_BASE_PATH, keyword, REPO_BASE_PATH);
+        if (matchedFiles.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No files found containing keyword: "${keyword}"`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${matchedFiles.length} matching files:\n${matchedFiles.join("\n")}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                { type: "text", text: `Error searching files: ${error.message}` },
+            ],
+            isError: true,
+        };
+    }
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case "read_api_spec":
+            return await handleReadApiSpec(args);
+        case "list_directory":
+            return await handleListDirectory(args);
+        case "search_files":
+            return await handleSearchFiles(args);
+        default:
+            throw new Error("Tool not found");
+    }
+});
+async function run() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`MCP Server "acw-repo-reader" is running on stdio.`);
+    console.error(`Watching repository path: ${REPO_BASE_PATH}`);
+}
+try {
+    await run();
+}
+catch (error) {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+}
+//# sourceMappingURL=index.js.map

package/index.ts

@@ -0,0 +1,243 @@
+#!/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 fs from "node:fs/promises";
+import path from "node:path";
+
+const rawRepoPath = process.env.REPO_BASE_PATH || process.argv[2];
+
+if (!rawRepoPath) {
+  const currentPath = process.cwd();
+  console.error("Error: REPO_BASE_PATH environment variable or a command-line argument is required.");
+  console.error(`\nHint: If you want to use the current directory, the absolute path is:\n${currentPath}`);
+  console.error(`\nUsage example:\nacw-repo-reader ${currentPath}`);
+  console.error("\nTips to find your repository path:");
+  console.error("- macOS: Right-click folder + hold 'Option' key -> Select 'Copy as Pathname'");
+  console.error("- Windows: Shift + Right-click folder -> Select 'Copy as path'");
+  process.exit(1);
+}
+
+const REPO_BASE_PATH = path.resolve(rawRepoPath);
+
+const server = new Server(
+  { name: "acw-repo-reader", version: "1.0.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "read_api_spec",
+        description:
+          "Reads API specifications, sequence diagrams, or any files from repository.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            filepath: {
+              type: "string",
+              description: "Relative path to the file inside the repo",
+            },
+          },
+          required: ["filepath"],
+        },
+      },
+      {
+        name: "list_directory",
+        description:
+          "List files and folders in a specific directory inside repository. Use this to find the exact filename before reading.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            dirPath: {
+              type: "string",
+              description:
+                "Relative directory path to list (e.g., '.' for root, or 'docs')",
+            },
+          },
+          required: ["dirPath"],
+        },
+      },
+      {
+        name: "search_files",
+        description:
+          "Search for files across the entire repository using a keyword (e.g., 'address', 'account'). Use this to find the exact filepath before reading.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            keyword: {
+              type: "string",
+              description:
+                "Keyword to search for in filenames (e.g., 'update-address' or '.http')",
+            },
+          },
+          required: ["keyword"],
+        },
+      },
+    ],
+  };
+});
+
+async function handleReadApiSpec(args: any) {
+  const filepath = typeof args?.filepath === "string" ? args.filepath : "";
+
+  if (!filepath) {
+    throw new Error("filepath is required and must be a string");
+  }
+
+  const fullPath = path.resolve(REPO_BASE_PATH, filepath);
+
+  if (!fullPath.startsWith(REPO_BASE_PATH)) {
+    console.error(`[Security Warning] Attempted path traversal: ${filepath}`);
+    throw new Error("Access denied: File is outside the repository base path.");
+  }
+
+  try {
+    const content = await fs.readFile(fullPath, "utf-8");
+    return {
+      content: [{ type: "text", text: content }],
+    };
+  } catch (error: any) {
+    return {
+      content: [{ type: "text", text: `Error reading file: ${error.message}` }],
+      isError: true,
+    };
+  }
+}
+
+async function handleListDirectory(args: any) {
+  const dirPath = typeof args?.dirPath === "string" ? args.dirPath : ".";
+  const fullDirPath = path.resolve(REPO_BASE_PATH, dirPath);
+
+  if (!fullDirPath.startsWith(REPO_BASE_PATH)) {
+    throw new Error("Access denied: Path is outside the repository base path.");
+  }
+
+  try {
+    const files = await fs.readdir(fullDirPath, { withFileTypes: true });
+    const fileList = files
+      .map(
+        (dirent) =>
+          `${dirent.isDirectory() ? "[DIR]" : "[FILE]"} ${dirent.name}`,
+      )
+      .join("\n");
+
+    return {
+      content: [{ type: "text", text: `Contents of ${dirPath}:\n${fileList}` }],
+    };
+  } catch (error: any) {
+    return {
+      content: [
+        { type: "text", text: `Error listing directory: ${error.message}` },
+      ],
+      isError: true,
+    };
+  }
+}
+
+async function findFilesRecursive(
+  dir: string,
+  keyword: string,
+  basePath: string,
+): Promise<string[]> {
+  let results: string[] = [];
+  const list = await fs.readdir(dir, { withFileTypes: true });
+
+  for (const file of list) {
+    if (
+      file.isDirectory() &&
+      (file.name === "node_modules" ||
+        file.name === ".git" ||
+        file.name === ".idea" ||
+        file.name === ".vscode")
+    ) {
+      continue;
+    }
+
+    const fullPath = path.resolve(dir, file.name);
+
+    if (file.isDirectory()) {
+      const subResults = await findFilesRecursive(fullPath, keyword, basePath);
+      results = results.concat(subResults);
+    } else if (file.name.toLowerCase().includes(keyword.toLowerCase())) {
+      results.push(path.relative(basePath, fullPath));
+    }
+  }
+  return results;
+}
+
+async function handleSearchFiles(args: any) {
+  const keyword = typeof args?.keyword === "string" ? args.keyword : "";
+
+  if (!keyword) {
+    throw new Error("keyword is required and must be a string");
+  }
+
+  try {
+    const matchedFiles = await findFilesRecursive(
+      REPO_BASE_PATH,
+      keyword,
+      REPO_BASE_PATH,
+    );
+
+    if (matchedFiles.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No files found containing keyword: "${keyword}"`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Found ${matchedFiles.length} matching files:\n${matchedFiles.join("\n")}`,
+        },
+      ],
+    };
+  } catch (error: any) {
+    return {
+      content: [
+        { type: "text", text: `Error searching files: ${error.message}` },
+      ],
+      isError: true,
+    };
+  }
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case "read_api_spec":
+      return await handleReadApiSpec(args);
+    case "list_directory":
+      return await handleListDirectory(args);
+    case "search_files":
+      return await handleSearchFiles(args);
+    default:
+      throw new Error("Tool not found");
+  }
+});
+
+async function run() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`MCP Server "acw-repo-reader" is running on stdio.`);
+  console.error(`Watching repository path: ${REPO_BASE_PATH}`);
+}
+
+try {
+  await run();
+} catch (error) {
+  console.error("Fatal error running server:", error);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "http-client-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server to explore and read files from a repository",
+  "main": "index.js",
+  "bin": {
+    "http-client-mcp-server": "./index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^6.0.2"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": [
+      "node"
+    ],
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}