sub-agents-mcp 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shinsuke Kagawa
+
+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,265 @@
+# Sub-Agents MCP Server
+
+Let your AI assistant (Cursor, Claude) use specialized sub-agents for specific tasks. For example, create a "test-writer" agent that writes tests, or a "code-reviewer" agent that reviews your code.
+
+## Prerequisites
+
+- Node.js 20 or higher
+- Cursor CLI or Claude Code installed
+- Basic terminal/command line knowledge
+
+## Installation
+
+```bash
+npx -y sub-agents-mcp
+```
+
+This command will install and run the MCP server. No manual building or cloning required!
+
+## Quick Start (3 minutes)
+
+### Step 1: Create Your First Agent
+
+Create a folder for your agents and add a file `code-reviewer.md`:
+
+```markdown
+# Code Reviewer
+
+You are a specialized AI assistant that reviews code.
+Focus on:
+- Finding bugs and potential issues
+- Suggesting improvements
+- Checking code quality
+```
+
+### Step 2: Setup Your AI Tool
+
+**For Cursor Users:**
+```bash
+# Install Cursor CLI
+curl https://cursor.com/install -fsS | bash
+
+# Login (Required!)
+cursor-agent login
+```
+
+**For Claude Code Users:**
+
+```bash
+# Option 1: NPM (requires Node.js 20+)
+npm install -g @anthropic-ai/claude-code
+
+# Option 2: Native install
+curl -fsSL claude.ai/install.sh | bash
+```
+
+### Step 3: Configure MCP
+
+**For Cursor:** Edit `~/.cursor/mcp.json`
+**For Claude:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+
+```json
+{
+  "mcpServers": {
+    "sub-agents": {
+      "command": "npx",
+      "args": ["-y", "sub-agents-mcp"],
+      "env": {
+        "AGENTS_DIR": "/path/to/your/agents-folder",  // ← Must be absolute path!
+        "AGENT_TYPE": "cursor"  // or "claude"
+      }
+    }
+  }
+}
+```
+
+**Path examples:**
+- ✅ Good: `/Users/john/Documents/my-agents` (Mac/Linux)
+- ✅ Good: `C:\\Users\\john\\Documents\\my-agents` (Windows)
+- ❌ Bad: `./agents` or `~/agents` (relative paths don't work)
+
+**That's it!** Restart your IDE and start using agents.
+
+## How to Use
+
+Once configured, just tell your AI assistant to use your agents:
+
+### Examples
+
+**Using a code reviewer:**
+```
+"Use the code-reviewer agent to check my UserService class"
+```
+
+**Using a test writer:**
+```
+"Use the test-writer agent to create unit tests for the auth module"
+```
+
+**Using a documentation writer:**
+```
+"Use the doc-writer agent to add JSDoc comments to all public methods"
+```
+
+Your AI will automatically invoke the specialized agent and return the results!
+
+## Common Agent Examples
+
+Here are some agents you might want to create:
+
+**`test-writer.md`** - Writes comprehensive unit tests
+```markdown
+# Test Writer
+You are specialized in writing unit tests.
+- Write tests that cover edge cases
+- Follow the project's testing patterns
+- Ensure good coverage
+```
+
+**`sql-expert.md`** - Helps with database queries
+```markdown
+# SQL Expert
+You are a database specialist.
+- Optimize queries for performance
+- Suggest proper indexes
+- Help with complex JOINs
+```
+
+**`security-checker.md`** - Reviews code for security issues
+```markdown
+# Security Checker
+You focus on finding security vulnerabilities.
+- Check for SQL injection risks
+- Identify authentication issues
+- Find potential data leaks
+```
+
+## Configuration
+
+### Required Settings
+
+**`AGENTS_DIR`** - Path to your agents folder
+- ⚠️ Must be an **absolute path**
+  - Mac/Linux: `/Users/john/my-agents`
+  - Windows: `C:\\Users\\john\\my-agents`
+- Create this folder before configuring MCP
+
+**`AGENT_TYPE`** - Which AI tool you're using
+- Set to `"cursor"` for Cursor
+- Set to `"claude"` for Claude Code
+
+### Optional Settings
+
+**`EXECUTION_TIMEOUT_MS`** - How long agents can run (default: 5 minutes)
+- Increase for complex tasks like document review
+- Maximum: 10 minutes (600000ms)
+
+### Creating Agents
+
+Each `.md` or `.txt` file in your agents folder becomes an available agent.
+
+**File naming tips:**
+- Filename = agent name (e.g., `test-writer.md` → use as "test-writer")
+- Use hyphens or underscores, no spaces
+
+**Agent file structure:**
+```markdown
+# Agent Name
+Describe what this agent specializes in.
+List its key capabilities.
+```
+
+### Security Note
+
+Agents have access to your project directory. Only use agent definitions from trusted sources.
+
+## Troubleshooting
+
+### Cursor CLI Not Working
+
+**Symptoms:** Timeout errors, authentication failures, or "session expired" messages
+
+**Solutions:**
+
+1. **Authenticate with cursor-agent login**
+   ```bash
+   cursor-agent login
+   ```
+   This is the standard authentication method. Run this command before using the MCP server.
+
+2. **Check if cursor-agent is installed**
+   ```bash
+   which cursor-agent
+   ```
+   If not found, reinstall Cursor CLI.
+
+3. **Verify session status**
+   If you're still having issues, your session may have expired. Simply run `cursor-agent login` again.
+
+### Agent Not Found
+
+1. Verify `AGENTS_DIR` points to the correct directory
+2. Check file has `.md` or `.txt` extension
+3. Ensure filename contains only allowed characters
+
+### Other Execution Errors
+
+1. Verify `AGENT_TYPE` is set correctly (`cursor` or `claude`)
+2. Ensure the CLI tool is installed and accessible:
+   - For `cursor`: Ensure `cursor-agent` CLI is installed and authenticated
+   - For `claude`: Ensure Claude Code CLI is installed
+3. Check environment variables are properly set
+
+
+## How It Works
+
+Your AI assistant can invoke specialized agents through MCP:
+1. You ask your AI to use an agent (e.g., "Use the test-writer agent")
+2. The MCP server runs the specialized agent with your request
+3. Results come back to your main AI assistant
+
+## Additional Configuration Examples
+
+### Full Configuration Reference
+
+**For Cursor:** `~/.cursor/mcp.json`
+```json
+{
+  "mcpServers": {
+    "sub-agents": {
+      "command": "npx",
+      "args": ["-y", "sub-agents-mcp"],
+      "env": {
+        "AGENTS_DIR": "/absolute/path/to/agents",
+        "AGENT_TYPE": "cursor",
+        "EXECUTION_TIMEOUT_MS": "300000"  // Optional: 5 minutes default
+      }
+    }
+  }
+}
+```
+
+**For Claude:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+```json
+{
+  "mcpServers": {
+    "sub-agents": {
+      "command": "npx",
+      "args": ["-y", "sub-agents-mcp"],
+      "env": {
+        "AGENTS_DIR": "/absolute/path/to/agents",
+        "AGENT_TYPE": "claude",
+        "EXECUTION_TIMEOUT_MS": "300000"  // Optional
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT
+
+---
+
+*Enable AI-to-AI collaboration through Model Context Protocol*

package/dist/agents/AgentManager.d.ts

@@ -0,0 +1,58 @@
+import type { ServerConfig } from '../config/ServerConfig';
+import type { AgentDefinition } from '../types/AgentDefinition';
+/**
+ * AgentManager class for discovering, loading, parsing, and caching agent definitions.
+ *
+ * Provides automatic detection of .md/.txt files in configured directory,
+ * parsing of Claude Code sub-agent format, and efficient caching with
+ * file change detection.
+ */
+export declare class AgentManager {
+    private config;
+    private logger;
+    constructor(config: ServerConfig);
+    /**
+     * Retrieves a specific agent definition by name.
+     *
+     * @param name - The name of the agent to retrieve
+     * @returns Promise resolving to the agent definition or undefined if not found
+     * @throws {Error} When agent name is invalid
+     */
+    getAgent(name: string): Promise<AgentDefinition | undefined>;
+    /**
+     * Lists all available agent definitions.
+     *
+     * @returns Promise resolving to an array of all agent definitions
+     */
+    listAgents(): Promise<AgentDefinition[]>;
+    /**
+     * Refreshes the agents by re-scanning the agents directory.
+     * Forces reload of all agent definitions from disk.
+     *
+     * @returns Promise resolving when refresh is complete
+     */
+    refreshAgents(): Promise<void>;
+    /**
+     * Loads all agent definitions from the configured directory.
+     * Scans for .md and .txt files and parses them as agent definitions.
+     *
+     * @returns Map of agent name to agent definition
+     */
+    private loadAgentsFromDirectory;
+    /**
+     * Loads and parses a single agent definition from a file.
+     *
+     * @param filePath - Absolute path to the agent definition file
+     * @returns Promise resolving to the parsed agent definition or undefined
+     */
+    private loadAgentFromFile;
+    /**
+     * Extracts description from agent file content.
+     * Looks for first heading or first line as description.
+     *
+     * @param content - The file content to parse
+     * @returns Extracted description or default message
+     */
+    private extractDescription;
+}
+//# sourceMappingURL=AgentManager.d.ts.map

package/dist/agents/AgentManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentManager.d.ts","sourceRoot":"","sources":["../../src/agents/AgentManager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAGhE;;;;;;GAMG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,MAAM,CAAQ;gBAEF,MAAM,EAAE,YAAY;IAIxC;;;;;;OAMG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAqClE;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAK9C;;;;;OAKG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;;;;OAKG;YACW,uBAAuB;IAsDrC;;;;;OAKG;YACW,iBAAiB;IAwC/B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;CAiB3B"}

package/dist/agents/AgentManager.js

@@ -0,0 +1,182 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentManager = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const Logger_1 = require("../utils/Logger");
+/**
+ * AgentManager class for discovering, loading, parsing, and caching agent definitions.
+ *
+ * Provides automatic detection of .md/.txt files in configured directory,
+ * parsing of Claude Code sub-agent format, and efficient caching with
+ * file change detection.
+ */
+class AgentManager {
+    constructor(config) {
+        this.config = config;
+        this.logger = new Logger_1.Logger(config.logLevel);
+    }
+    /**
+     * Retrieves a specific agent definition by name.
+     *
+     * @param name - The name of the agent to retrieve
+     * @returns Promise resolving to the agent definition or undefined if not found
+     * @throws {Error} When agent name is invalid
+     */
+    async getAgent(name) {
+        // Input validation for security
+        if (!name || typeof name !== 'string') {
+            throw new Error('Invalid agent name: agent name is required');
+        }
+        if (name.trim().length === 0) {
+            throw new Error('Invalid agent name: empty agent name not allowed');
+        }
+        if (name.length > 255) {
+            throw new Error('Invalid agent name: too long agent name');
+        }
+        // Check for invalid characters that could be used for path traversal or injection
+        const invalidChars = /[<>:"/\\|?*;`$()&|\s]/;
+        if (invalidChars.test(name)) {
+            throw new Error('Invalid agent name: forbidden characters detected');
+        }
+        // Check for control characters using char code inspection
+        for (let i = 0; i < name.length; i++) {
+            const charCode = name.charCodeAt(i);
+            if ((charCode >= 0 && charCode <= 31) || charCode === 127) {
+                throw new Error('Invalid agent name: forbidden characters detected');
+            }
+        }
+        // Check for path traversal attempts
+        if (name.includes('..') || name.includes('./') || name.includes('.\\')) {
+            throw new Error('Invalid agent name: path traversal attempt detected');
+        }
+        const agents = await this.loadAgentsFromDirectory();
+        return agents.get(name);
+    }
+    /**
+     * Lists all available agent definitions.
+     *
+     * @returns Promise resolving to an array of all agent definitions
+     */
+    async listAgents() {
+        const agents = await this.loadAgentsFromDirectory();
+        return Array.from(agents.values());
+    }
+    /**
+     * Refreshes the agents by re-scanning the agents directory.
+     * Forces reload of all agent definitions from disk.
+     *
+     * @returns Promise resolving when refresh is complete
+     */
+    async refreshAgents() {
+        await this.loadAgentsFromDirectory();
+    }
+    /**
+     * Loads all agent definitions from the configured directory.
+     * Scans for .md and .txt files and parses them as agent definitions.
+     *
+     * @returns Map of agent name to agent definition
+     */
+    async loadAgentsFromDirectory() {
+        try {
+            const agentsDir = node_path_1.default.resolve(this.config.agentsDir);
+            this.logger.info('Starting agent discovery', { directory: agentsDir });
+            const files = await node_fs_1.default.promises.readdir(agentsDir);
+            const agentFiles = files.filter((file) => file.endsWith('.md') || file.endsWith('.txt'));
+            this.logger.info('Agent definition files discovered', {
+                totalFiles: files.length,
+                agentFiles: agentFiles.length,
+                files: agentFiles,
+            });
+            const agents = new Map();
+            for (const file of agentFiles) {
+                const filePath = node_path_1.default.join(agentsDir, file);
+                try {
+                    const agent = await this.loadAgentFromFile(filePath);
+                    if (agent) {
+                        agents.set(agent.name, agent);
+                        this.logger.debug('Agent definition loaded successfully', {
+                            name: agent.name,
+                            filePath: agent.filePath,
+                            description: agent.description,
+                        });
+                    }
+                }
+                catch (error) {
+                    this.logger.error('Failed to load agent definition from file', error instanceof Error ? error : undefined, { filePath });
+                }
+            }
+            this.logger.info('Agent discovery completed', {
+                loadedAgents: agents.size,
+                timestamp: new Date().toISOString(),
+            });
+            return agents;
+        }
+        catch (error) {
+            this.logger.error('Failed to scan agents directory', error instanceof Error ? error : undefined, { directory: this.config.agentsDir });
+            throw new Error(`Failed to load agents from directory: ${this.config.agentsDir}`);
+        }
+    }
+    /**
+     * Loads and parses a single agent definition from a file.
+     *
+     * @param filePath - Absolute path to the agent definition file
+     * @returns Promise resolving to the parsed agent definition or undefined
+     */
+    async loadAgentFromFile(filePath) {
+        try {
+            this.logger.debug('Loading agent definition from file', { filePath });
+            const content = await node_fs_1.default.promises.readFile(filePath, 'utf-8');
+            const stats = await node_fs_1.default.promises.stat(filePath);
+            // Extract agent name from filename (without extension)
+            const fileName = node_path_1.default.basename(filePath);
+            const agentName = fileName.replace(/\.(md|txt)$/, '');
+            // Parse description from content (first line or first heading)
+            const description = this.extractDescription(content);
+            const agentDefinition = {
+                name: agentName,
+                description,
+                content,
+                filePath,
+                lastModified: stats.mtime,
+            };
+            this.logger.debug('Agent definition parsed successfully', {
+                name: agentName,
+                description,
+                contentLength: content.length,
+                lastModified: stats.mtime?.toISOString() ?? 'unknown',
+            });
+            return agentDefinition;
+        }
+        catch (error) {
+            this.logger.error('Error reading agent definition file', error instanceof Error ? error : undefined, { filePath });
+            return undefined;
+        }
+    }
+    /**
+     * Extracts description from agent file content.
+     * Looks for first heading or first line as description.
+     *
+     * @param content - The file content to parse
+     * @returns Extracted description or default message
+     */
+    extractDescription(content) {
+        const lines = content.split('\n').filter((line) => line.trim());
+        // Look for first markdown heading
+        for (const line of lines) {
+            if (line.startsWith('#')) {
+                return line.replace(/^#+\s*/, '').trim();
+            }
+        }
+        // Fall back to first non-empty line
+        if (lines.length > 0 && lines[0]) {
+            return lines[0].trim();
+        }
+        return 'Agent definition';
+    }
+}
+exports.AgentManager = AgentManager;
+//# sourceMappingURL=AgentManager.js.map

package/dist/agents/AgentManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentManager.js","sourceRoot":"","sources":["../../src/agents/AgentManager.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAwB;AACxB,0DAA4B;AAG5B,6CAAqE;AAErE;;;;;;GAMG;AACH,MAAa,YAAY;IAGvB,YAAoB,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;QACtC,IAAI,CAAC,MAAM,GAAG,IAAI,eAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAChD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,gCAAgC;QAChC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;QAC/D,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAA;QACrE,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;QAC5D,CAAC;QAED,kFAAkF;QAClF,MAAM,YAAY,GAAG,uBAAuB,CAAA;QAC5C,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;QACtE,CAAC;QAED,0DAA0D;QAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;YACnC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,EAAE,CAAC,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;gBAC1D,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;YACtE,CAAC;QACH,CAAC;QAED,oCAAoC;QACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;QACxE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,uBAAuB,EAAE,CAAA;QACnD,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU;QACd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,uBAAuB,EAAE,CAAA;QACnD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;IACpC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,IAAI,CAAC,uBAAuB,EAAE,CAAA;IACtC,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,uBAAuB;QACnC,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;YACrD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAA;YAEtE,MAAM,KAAK,GAAG,MAAM,iBAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;YAElD,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;YAExF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE;gBACpD,UAAU,EAAE,KAAK,CAAC,MAAM;gBACxB,UAAU,EAAE,UAAU,CAAC,MAAM;gBAC7B,KAAK,EAAE,UAAU;aAClB,CAAC,CAAA;YAEF,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAA;YAEjD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;gBAC9B,MAAM,QAAQ,GAAG,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAA;gBAC3C,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAA;oBACpD,IAAI,KAAK,EAAE,CAAC;wBACV,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;wBAC7B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,EAAE;4BACxD,IAAI,EAAE,KAAK,CAAC,IAAI;4BAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;4BACxB,WAAW,EAAE,KAAK,CAAC,WAAW;yBAC/B,CAAC,CAAA;oBACJ,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,2CAA2C,EAC3C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAC1C,EAAE,QAAQ,EAAE,CACb,CAAA;gBACH,CAAC;YACH,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE;gBAC5C,YAAY,EAAE,MAAM,CAAC,IAAI;gBACzB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC,CAAA;YAEF,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,iCAAiC,EACjC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAC1C,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CACrC,CAAA;YACD,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAA;QACnF,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,iBAAiB,CAAC,QAAgB;QAC9C,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAA;YAErE,MAAM,OAAO,GAAG,MAAM,iBAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;YAC7D,MAAM,KAAK,GAAG,MAAM,iBAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YAE9C,uDAAuD;YACvD,MAAM,QAAQ,GAAG,mBAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;YACxC,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA;YAErD,+DAA+D;YAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAA;YAEpD,MAAM,eAAe,GAAoB;gBACvC,IAAI,EAAE,SAAS;gBACf,WAAW;gBACX,OAAO;gBACP,QAAQ;gBACR,YAAY,EAAE,KAAK,CAAC,KAAK;aAC1B,CAAA;YAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,EAAE;gBACxD,IAAI,EAAE,SAAS;gBACf,WAAW;gBACX,aAAa,EAAE,OAAO,CAAC,MAAM;gBAC7B,YAAY,EAAE,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,SAAS;aACtD,CAAC,CAAA;YAEF,OAAO,eAAe,CAAA;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,qCAAqC,EACrC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAC1C,EAAE,QAAQ,EAAE,CACb,CAAA;YACD,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,kBAAkB,CAAC,OAAe;QACxC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;QAE/D,kCAAkC;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;YAC1C,CAAC;QACH,CAAC;QAED,oCAAoC;QACpC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACxB,CAAC;QAED,OAAO,kBAAkB,CAAA;IAC3B,CAAC;CACF;AAzMD,oCAyMC"}

package/dist/config/ServerConfig.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Server configuration management class.
+ *
+ * Handles loading configuration from environment variables with fallback defaults,
+ * validates configuration values, and provides type-safe access to server settings.
+ *
+ * Environment variables:
+ * - SERVER_NAME: Name identifier for the MCP server (default: 'sub-agents-mcp-server')
+ * - SERVER_VERSION: Version of the MCP server (default: '1.0.0')
+ * - AGENTS_DIR: Directory containing agent definition files (REQUIRED - must be absolute path)
+ * - AGENT_TYPE: Type of agent to use ('cursor' | 'claude') (default: 'cursor')
+ * - LOG_LEVEL: Log level for server operations (default: 'info')
+ */
+export declare class ServerConfig {
+    /** Server name identifier used for MCP registration */
+    readonly serverName: string;
+    /** Server version used for identification */
+    readonly serverVersion: string;
+    /** Directory path containing agent definition markdown files */
+    readonly agentsDir: string;
+    /** Type of agent to use for execution */
+    readonly agentType: 'cursor' | 'claude';
+    /** Log level for server operations */
+    readonly logLevel: 'debug' | 'info' | 'warn' | 'error';
+    /** Maximum execution timeout in milliseconds for agent execution */
+    readonly executionTimeoutMs: number;
+    /**
+     * Creates a new ServerConfig instance by loading values from environment variables
+     * or using default values.
+     * @throws {Error} When AGENTS_DIR environment variable is not set
+     */
+    constructor();
+}
+//# sourceMappingURL=ServerConfig.d.ts.map

package/dist/config/ServerConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerConfig.d.ts","sourceRoot":"","sources":["../../src/config/ServerConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,uDAAuD;IACvD,SAAgB,UAAU,EAAE,MAAM,CAAA;IAElC,6CAA6C;IAC7C,SAAgB,aAAa,EAAE,MAAM,CAAA;IAErC,gEAAgE;IAChE,SAAgB,SAAS,EAAE,MAAM,CAAA;IAEjC,yCAAyC;IACzC,SAAgB,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAE9C,sCAAsC;IACtC,SAAgB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;IAE7D,oEAAoE;IACpE,SAAgB,kBAAkB,EAAE,MAAM,CAAA;IAE1C;;;;OAIG;;CAkCJ"}

package/dist/config/ServerConfig.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerConfig = void 0;
+/**
+ * Server configuration management class.
+ *
+ * Handles loading configuration from environment variables with fallback defaults,
+ * validates configuration values, and provides type-safe access to server settings.
+ *
+ * Environment variables:
+ * - SERVER_NAME: Name identifier for the MCP server (default: 'sub-agents-mcp-server')
+ * - SERVER_VERSION: Version of the MCP server (default: '1.0.0')
+ * - AGENTS_DIR: Directory containing agent definition files (REQUIRED - must be absolute path)
+ * - AGENT_TYPE: Type of agent to use ('cursor' | 'claude') (default: 'cursor')
+ * - LOG_LEVEL: Log level for server operations (default: 'info')
+ */
+class ServerConfig {
+    /**
+     * Creates a new ServerConfig instance by loading values from environment variables
+     * or using default values.
+     * @throws {Error} When AGENTS_DIR environment variable is not set
+     */
+    constructor() {
+        this.serverName = process.env['SERVER_NAME'] || 'sub-agents-mcp';
+        this.serverVersion = process.env['SERVER_VERSION'] || '0.1.0';
+        // AGENTS_DIR is required for MCP to work correctly
+        const agentsDir = process.env['AGENTS_DIR'];
+        if (!agentsDir) {
+            throw new Error('AGENTS_DIR environment variable is required.\n' +
+                'Please set it to an absolute path in your MCP configuration.\n' +
+                'Example for Cursor IDE (~/.cursor/mcp.json):\n' +
+                '  "env": {\n' +
+                '    "AGENTS_DIR": "/Users/username/projects/my-app/agents"\n' +
+                '  }\n' +
+                'Example for Claude Desktop:\n' +
+                '  "env": {\n' +
+                '    "AGENTS_DIR": "/Users/username/claude-agents"\n' +
+                '  }');
+        }
+        this.agentsDir = agentsDir;
+        this.agentType = process.env['AGENT_TYPE'] || 'cursor';
+        this.logLevel = process.env['LOG_LEVEL'] || 'info';
+        const timeoutEnv = process.env['EXECUTION_TIMEOUT_MS'];
+        if (timeoutEnv?.trim()) {
+            const parsedTimeout = Number.parseInt(timeoutEnv, 10);
+            this.executionTimeoutMs = Number.isNaN(parsedTimeout) ? 300000 : parsedTimeout;
+        }
+        else {
+            this.executionTimeoutMs = 300000;
+        }
+    }
+}
+exports.ServerConfig = ServerConfig;
+//# sourceMappingURL=ServerConfig.js.map

package/dist/config/ServerConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerConfig.js","sourceRoot":"","sources":["../../src/config/ServerConfig.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,MAAa,YAAY;IAmBvB;;;;OAIG;IACH;QACE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,gBAAgB,CAAA;QAChE,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,OAAO,CAAA;QAE7D,mDAAmD;QACnD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;QAC3C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,gDAAgD;gBAC9C,gEAAgE;gBAChE,gDAAgD;gBAChD,cAAc;gBACd,8DAA8D;gBAC9D,OAAO;gBACP,+BAA+B;gBAC/B,cAAc;gBACd,qDAAqD;gBACrD,KAAK,CACR,CAAA;QACH,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAE1B,IAAI,CAAC,SAAS,GAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAyB,IAAI,QAAQ,CAAA;QAC/E,IAAI,CAAC,QAAQ,GAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAyC,IAAI,MAAM,CAAA;QAE3F,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAA;QACtD,IAAI,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC;YACvB,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;YACrD,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAA;QAChF,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAA;QAClC,CAAC;IACH,CAAC;CACF;AAzDD,oCAyDC"}