kadins-personal-mcp 1.0.0 → 1.0.1

package/README.md

@@ -42,32 +42,60 @@ npm run dev
 - `file_permissions`: Change file permissions
 - `directory_create`: Create a new directory
 - `directory_list`: List directory contents with details
+- `directory_tree`: Generate a tree diagram of a directory structure
+- `file_edit`: Edit file content by replacing specific text
+- `file_glob`: Find files using glob patterns
+- `list_files`: List files and subdirectories in a directory
+- `write_file`: Create or overwrite a file with specified content
 
 ### System Tools
 - `run_command`: Execute shell commands on the system
+- `shell_command`: Execute shell commands with more options
 - `read_file`: Read the contents of a file
-- `calculator`: Perform basic mathematical calculations
-- `get_current_time`: Get the current date and time
-- `file_echo`: Echo messages back
+- `read_many_files`: Read content from multiple files
+- `text_search`: Search for text patterns within files using grep
+
+### Network Tools
+- `web_fetch`: Fetch content from a specified URL
 
 ## Configuration
 
 The server can be configured to work with various MCP-compatible clients like Cursor, Claude Desktop, and Windsurf.
 
-To configure your MCP client, add the following entry to your MCP configuration file (e.g., `~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, or Claude Desktop config):
+### For Local Installation (Recommended for Development)
+
+Since you've installed the package globally with `npm install -g .`, the MCP client can directly execute the command. Add the following entry to your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "kadins-personal-mcp": {
+      "command": "kadins-personal-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### For Direct Path Installation
+
+If the above doesn't work, you can also configure it to run directly with node:
 
 ```json
 {
   "mcpServers": {
     "kadins-personal-mcp": {
       "command": "node",
-      "args": ["/path/to/kadins-personal-mcp/dist/index.js"]
+      "args": ["/Users/kadin/.nvm/versions/node/v22.21.1/lib/node_modules/kadins-personal-mcp/dist/index.js"]
     }
   }
 }
 ```
 
-Replace `/path/to/kadins-personal-mcp/dist/index.js` with the actual path to the built index.js file in your installation.
+Replace the path with the actual path to the installed package. You can find the correct path by running:
+```bash
+npm list -g --depth=0 kadins-personal-mcp
+```
 
 For Claude Desktop, the configuration file is typically located at:
 `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS
@@ -96,6 +124,12 @@ To run tests:
 npm run test
 ```
 
+## System Prompt
+
+For AI models to properly understand and use these tools, refer to the SYSTEM_PROMPT.md file which contains a comprehensive system prompt explaining all available tools and their usage.
+
+For integration with existing AI systems, see INTEGRATED_SYSTEM_PROMPT.md which combines the Kadins Personal MCP tools information with a standard AI system prompt template.
+
 ## License
 
 MIT

package/dist/{chunk-T6KZEVGN.js → chunk-IFFK3HCL.js}

@@ -6,11 +6,14 @@ var __commonJS = (cb, mod) => function __require() {
 // src/toolLoader.ts
 import fs from "fs";
 import path from "path";
+import { fileURLToPath } from "url";
 function isValidTool(module) {
   return typeof module.name === "string" && typeof module.description === "string" && typeof module.parameters === "object" && typeof module.handler === "function";
 }
 async function loadTools(server) {
-  const toolsDir = path.join(process.cwd(), "tools");
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+  const toolsDir = path.join(__dirname, "..", "tools");
   if (!fs.existsSync(toolsDir)) {
     console.error(`Tools directory does not exist: ${toolsDir}`);
     return;

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   __commonJS,
   loadTools
-} from "./chunk-T6KZEVGN.js";
+} from "./chunk-IFFK3HCL.js";
 
 // package.json
 var require_package = __commonJS({
@@ -17,6 +17,11 @@ var require_package = __commonJS({
       bin: {
         "kadins-personal-mcp": "./kadins-personal-mcp.js"
       },
+      files: [
+        "dist/**/*",
+        "tools/**/*",
+        "kadins-personal-mcp.js"
+      ],
       scripts: {
         dev: "node --loader ts-node/esm src/index.ts",
         build: "tsup src/index.ts src/toolLoader.ts --format esm --dts --clean",
@@ -25,6 +30,8 @@ var require_package = __commonJS({
       },
       dependencies: {
         "@modelcontextprotocol/sdk": "^1.8.0",
+        glob: "^10.3.10",
+        "node-fetch": "^3.3.2",
         zod: "^3.24.2"
       },
       devDependencies: {
@@ -59,7 +66,6 @@ var require_package = __commonJS({
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
 var packageJson = require_package();
 var server = new McpServer(
   {
@@ -70,26 +76,6 @@ var server = new McpServer(
     instructions: "These tools communicate with a reference Model Context Protocol (MCP) server."
   }
 );
-server.tool(
-  "ping_pong",
-  "Ping the server and receive a pong back",
-  {},
-  async () => {
-    return {
-      content: [{ type: "text", text: "pong" }]
-    };
-  }
-);
-server.tool(
-  "echo",
-  "Send a message to the server and receive the message back",
-  { message: z.string() },
-  async (params) => {
-    return {
-      content: [{ type: "text", text: params.message }]
-    };
-  }
-);
 async function run() {
   try {
     await loadTools(server);

package/dist/toolLoader.js

@@ -1,6 +1,6 @@
 import {
   loadTools
-} from "./chunk-T6KZEVGN.js";
+} from "./chunk-IFFK3HCL.js";
 export {
   loadTools
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kadins-personal-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Kadin's Personal MCP Server with comprehensive file system and command tools",
   "author": "Kadin",
   "license": "MIT",
@@ -8,6 +8,11 @@
   "bin": {
     "kadins-personal-mcp": "./kadins-personal-mcp.js"
   },
+  "files": [
+    "dist/**/*",
+    "tools/**/*",
+    "kadins-personal-mcp.js"
+  ],
   "scripts": {
     "dev": "node --loader ts-node/esm src/index.ts",
     "build": "tsup src/index.ts src/toolLoader.ts --format esm --dts --clean",
@@ -16,6 +21,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.8.0",
+    "glob": "^10.3.10",
+    "node-fetch": "^3.3.2",
     "zod": "^3.24.2"
   },
   "devDependencies": {
@@ -30,7 +37,9 @@
   "jest": {
     "preset": "ts-jest/presets/default-esm",
     "testEnvironment": "node",
-    "extensionsToTreatAsEsm": [".ts"],
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
     "moduleNameMapper": {
       "^(\\.{1,2}/.*)\\.js$": "$1"
     },
@@ -43,4 +52,4 @@
       ]
     }
   }
-}
+}

package/tools/fileEdit.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+export const name = "file_edit";
+export const description = "Edit the content of a file by replacing specific text segments";
+export const parameters = {
+  file_path: z.string().describe("The absolute path to the file to edit"),
+  old_content: z.string().describe("The exact literal text to replace"),
+  new_content: z.string().describe("The exact literal text to replace with"),
+  replace_all: z.boolean().describe("Replace all occurrences of old_content (default false)").optional().default(false)
+};
+export const handler = async (params: { file_path: string; old_content: string; new_content: string; replace_all: boolean }) => {
+  try {
+    const fs = await import("fs");
+    const path = await import("path");
+    
+    // Resolve the path relative to the current working directory
+    const resolvedPath = path.resolve(params.file_path);
+    
+    // Allow editing any accessible file
+    if (!fs.existsSync(resolvedPath)) {
+      return {
+        content: [{ type: "text", text: `Error: File does not exist: ${params.file_path}` }]
+      };
+    }
+    
+    const stat = fs.statSync(resolvedPath);
+    if (stat.isDirectory()) {
+      return {
+        content: [{ type: "text", text: `Error: Path is a directory, not a file: ${params.file_path}` }]
+      };
+    }
+    
+    // Limit file size to prevent huge operations
+    const maxSize = 1024 * 100; // 100KB limit
+    if (stat.size > maxSize) {
+      return {
+        content: [{ type: "text", text: `Error: File is too large to edit (${Math.round(stat.size / 1024)}KB). Maximum allowed size is 100KB.` }]
+      };
+    }
+    
+    let content = fs.readFileSync(resolvedPath, "utf-8");
+    
+    // Perform the replacement
+    let newFileContent;
+    if (params.replace_all) {
+      newFileContent = content.split(params.old_content).join(params.new_content);
+    } else {
+      // Only replace first occurrence
+      const index = content.indexOf(params.old_content);
+      if (index === -1) {
+        return {
+          content: [{ type: "text", text: `Error: The specified text to replace was not found in the file: ${params.file_path}` }]
+        };
+      }
+      newFileContent = content.substring(0, index) + 
+                      params.new_content + 
+                      content.substring(index + params.old_content.length);
+    }
+    
+    // Write the updated content back to the file
+    fs.writeFileSync(resolvedPath, newFileContent, "utf-8");
+    
+    return {
+      content: [{ type: "text", text: `Successfully updated file: ${params.file_path}. Replaced ${params.replace_all ? 'all' : 'first'} occurrence(s) of specified text.` }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error editing file: ${(error as Error).message}` }]
+    };
+  }
+};

package/tools/fileGlob.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+export const name = "file_glob";
+export const description = "Find files using glob patterns";
+export const parameters = {
+  pattern: z.string().describe("The glob pattern to match files against (e.g., '**/*.js', '*.ts')")
+};
+export const handler = async (params: { pattern: string }) => {
+  try {
+    const { glob } = await import("glob");
+    
+    // Execute the glob pattern to find matching files
+    const files = await new Promise<string[]>((resolve, reject) => {
+      glob(params.pattern, (err, matches) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(matches);
+        }
+      });
+    });
+    
+    if (files.length === 0) {
+      return {
+        content: [{ type: "text", text: `No files found matching pattern: ${params.pattern}` }]
+      };
+    }
+    
+    // Limit results to prevent huge responses
+    const limitedFiles = files.slice(0, 100); // Limit to first 100 files
+    let response = `Found ${files.length} file(s) matching pattern "${params.pattern}":\n${limitedFiles.join("\n")}`;
+    
+    if (files.length > 100) {
+      response += `\n\n... and ${files.length - 100} more files`;
+    }
+    
+    return {
+      content: [{ type: "text", text: response }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error finding files with glob pattern: ${(error as Error).message}` }]
+    };
+  }
+};

package/tools/listFiles.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+
+export const name = "list_files";
+export const description = "List the names of files and subdirectories in a specified directory";
+export const parameters = {
+  path: z.string().describe("The directory path to list").optional().default("."),
+  show_hidden: z.boolean().describe("Whether to show hidden files/directories").optional().default(false),
+  max_items: z.number().describe("Maximum number of items to return").optional().default(100)
+};
+export const handler = async (params: { path: string; show_hidden: boolean; max_items: number }) => {
+  try {
+    const fs = await import("fs");
+    const path = await import("path");
+    
+    const resolvedPath = path.resolve(params.path);
+    
+    // Allow listing any accessible directory
+    if (!fs.existsSync(resolvedPath)) {
+      return {
+        content: [{ type: "text", text: `Error: Directory does not exist: ${params.path}` }]
+      };
+    }
+    
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isDirectory()) {
+      return {
+        content: [{ type: "text", text: `Error: Path is not a directory: ${params.path}` }]
+      };
+    }
+    
+    const items = fs.readdirSync(resolvedPath).filter(item => {
+      if (!params.show_hidden && item.startsWith('.')) {
+        return false;
+      }
+      return true;
+    });
+    
+    // Limit number of items returned
+    const limitedItems = items.slice(0, params.max_items);
+    
+    let response = `Contents of directory "${params.path}":\n`;
+    
+    for (const item of limitedItems) {
+      const itemPath = path.join(resolvedPath, item);
+      const itemStat = fs.statSync(itemPath);
+      const type = itemStat.isDirectory() ? "[DIR]" : "[FILE]";
+      const size = itemStat.isDirectory() ? "" : ` (${itemStat.size} bytes)`;
+      response += `${type} ${item}${size}\n`;
+    }
+    
+    if (items.length > params.max_items) {
+      response += `\n... and ${items.length - params.max_items} more items`;
+    }
+    
+    return {
+      content: [{ type: "text", text: response }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error listing directory: ${(error as Error).message}` }]
+    };
+  }
+};

package/tools/readManyFiles.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+
+export const name = "read_many_files";
+export const description = "Read content from multiple files specified by paths";
+export const parameters = {
+  paths: z.array(z.string()).describe("An array of file paths to read"),
+  max_file_size: z.number().describe("Maximum file size to read in KB").optional().default(100)
+};
+export const handler = async (params: { paths: string[]; max_file_size: number }) => {
+  try {
+    const fs = await import("fs");
+    const path = await import("path");
+    
+    let response = "";
+    const maxSize = params.max_file_size * 1024; // Convert to bytes
+    
+    for (const filePath of params.paths) {
+      const resolvedPath = path.resolve(filePath);
+      
+      if (!fs.existsSync(resolvedPath)) {
+        response += `--- File not found: ${filePath} ---\n\n`;
+        continue;
+      }
+      
+      const stat = fs.statSync(resolvedPath);
+      if (stat.isDirectory()) {
+        response += `--- Path is a directory: ${filePath} ---\n\n`;
+        continue;
+      }
+      
+      if (stat.size > maxSize) {
+        response += `--- File too large to read (${Math.round(stat.size / 1024)}KB): ${filePath} ---\n\n`;
+        continue;
+      }
+      
+      try {
+        const content = fs.readFileSync(resolvedPath, "utf-8");
+        response += `--- ${filePath} ---\n${content}\n--- End of ${filePath} ---\n\n`;
+      } catch (error) {
+        response += `--- Error reading file: ${filePath} - ${(error as Error).message} ---\n\n`;
+      }
+    }
+    
+    // Limit total response size
+    if (response.length > 10000) { // Limit to 10KB
+      response = response.substring(0, 10000) + '\n\n... (response truncated)';
+    }
+    
+    return {
+      content: [{ type: "text", text: response }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error reading files: ${(error as Error).message}` }]
+    };
+  }
+};

package/tools/shellCommand.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+
+export const name = "shell_command";
+export const description = "Execute shell commands on the system";
+export const parameters = {
+  command: z.string().describe("The shell command to execute"),
+  timeout: z.number().describe("Command timeout in seconds").optional().default(30)
+};
+export const handler = async (params: { command: string; timeout: number }) => {
+  try {
+    // Dynamically import child_process
+    const { exec } = await import("child_process");
+    const util = await import("util");
+
+    // Use util.promisify to convert exec to a promise-based function
+    const execPromise = util.promisify(exec);
+
+    // Validate command to prevent potentially dangerous operations
+    const dangerousCommands = ['rm -rf /', 'dd', 'mkfs', 'format', '>:', '>/dev/null'];
+    for (const dangerousCmd of dangerousCommands) {
+      if (params.command.toLowerCase().includes(dangerousCmd)) {
+        return {
+          content: [
+            { type: "text", text: `Error: Command contains potentially dangerous operation: ${dangerousCmd}` }
+          ]
+        };
+      }
+    }
+
+    // Execute the command with a timeout for safety
+    const { stdout, stderr } = await Promise.race([
+      execPromise(params.command),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`Command timed out after ${params.timeout} seconds`)), params.timeout * 1000)
+      )
+    ]);
+
+    // Limit output size to prevent huge responses
+    let output = stdout || stderr || 'Command executed successfully with no output';
+    if (output.length > 5000) { // Limit to 5000 characters
+      output = output.substring(0, 5000) + '\n... (output truncated)';
+    }
+
+    // Return both stdout and stderr
+    return {
+      content: [
+        { type: "text", text: `Command: ${params.command}\n\nOutput:\n${output}` }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        { type: "text", text: `Error executing command: ${params.command}\n\nError: ${(error as Error).message}` }
+      ]
+    };
+  }
+};

package/tools/textSearch.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+export const name = "text_search";
+export const description = "Search for text patterns within files using grep";
+export const parameters = {
+  pattern: z.string().describe("The text pattern to search for (supports regex)"),
+  path: z.string().describe("The file or directory path to search in").optional().default("."),
+  case_sensitive: z.boolean().describe("Whether the search is case sensitive").optional().default(true)
+};
+export const handler = async (params: { pattern: string; path: string; case_sensitive: boolean }) => {
+  try {
+    const { exec } = await import("child_process");
+    const util = await import("util");
+    
+    // Use util.promisify to convert exec to a promise-based function
+    const execPromise = util.promisify(exec);
+    
+    // Build the grep command
+    let command = "grep -r -n --color=never ";
+    if (!params.case_sensitive) {
+      command += "-i ";
+    }
+    command += `"${params.pattern}" "${params.path}"`;
+    
+    // Execute the command with a timeout for safety
+    const { stdout, stderr } = await Promise.race([
+      execPromise(command),
+      new Promise((_, reject) => 
+        setTimeout(() => reject(new Error('Search timed out after 15 seconds')), 15000)
+      )
+    ]);
+    
+    // Limit output size to prevent huge responses
+    let output = stdout || stderr || `No matches found for pattern: ${params.pattern}`;
+    if (output.length > 5000) { // Limit to 5000 characters
+      output = output.substring(0, 5000) + '\n... (output truncated)';
+    }
+    
+    return {
+      content: [
+        { type: "text", text: `Search results for pattern "${params.pattern}" in path "${params.path}":\n\n${output}` }
+      ]
+    };
+  } catch (error) {
+    // If grep command fails (e.g., no matches), return a friendly message
+    if ((error as any).code === 1) {
+      // Exit code 1 in grep means no matches found, which is not a real error
+      return {
+        content: [
+          { type: "text", text: `No matches found for pattern: ${params.pattern}` }
+        ]
+      };
+    }
+    
+    return {
+      content: [
+        { type: "text", text: `Error searching for pattern: ${(error as Error).message}` }
+      ]
+    };
+  }
+};

package/tools/webFetch.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+export const name = "web_fetch";
+export const description = "Fetch content from a specified URL";
+export const parameters = {
+  url: z.string().describe("The URL to fetch content from"),
+  max_content_size: z.number().describe("Maximum content size to fetch in KB").optional().default(500)
+};
+export const handler = async (params: { url: string; max_content_size: number }) => {
+  try {
+    const { default: fetch } = await import("node-fetch");
+    
+    // Fetch the content from the URL
+    const response = await fetch(params.url);
+    
+    if (!response.ok) {
+      return {
+        content: [{ type: "text", text: `Error: Failed to fetch URL. Status: ${response.status} ${response.statusText}` }]
+      };
+    }
+    
+    // Check content length header if available
+    const contentLength = response.headers.get('content-length');
+    if (contentLength) {
+      const sizeInKB = parseInt(contentLength) / 1024;
+      if (sizeInKB > params.max_content_size) {
+        return {
+          content: [{ type: "text", text: `Error: Content is too large to fetch (${sizeInKB.toFixed(2)}KB). Maximum allowed size is ${params.max_content_size}KB.` }]
+        };
+      }
+    }
+    
+    const content = await response.text();
+    
+    // Limit content size
+    const maxSize = params.max_content_size * 1024; // Convert to bytes
+    let limitedContent = content;
+    if (content.length > maxSize) {
+      limitedContent = content.substring(0, maxSize) + '\n\n... (content truncated)';
+    }
+    
+    return {
+      content: [{ type: "text", text: `Content from ${params.url}:\n\n${limitedContent}` }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error fetching URL: ${(error as Error).message}` }]
+    };
+  }
+};

package/tools/writeFile.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+export const name = "write_file";
+export const description = "Create or overwrite a file with specified content";
+export const parameters = {
+  file_path: z.string().describe("The absolute path to the file to write"),
+  content: z.string().describe("The content to write to the file"),
+  create_directories: z.boolean().describe("Whether to create parent directories if they don't exist").optional().default(true)
+};
+export const handler = async (params: { file_path: string; content: string; create_directories: boolean }) => {
+  try {
+    const fs = await import("fs");
+    const path = await import("path");
+    
+    // Resolve the path relative to the current working directory
+    const resolvedPath = path.resolve(params.file_path);
+    
+    // Allow writing to any accessible path
+    if (params.create_directories) {
+      // Create parent directories if they don't exist
+      const dir = path.dirname(resolvedPath);
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    
+    // Write the content to the file
+    fs.writeFileSync(resolvedPath, params.content, "utf-8");
+    
+    return {
+      content: [{ type: "text", text: `Successfully wrote ${params.content.length} characters to ${params.file_path}` }]
+    };
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error writing file: ${(error as Error).message}` }]
+    };
+  }
+};