sdl-mcp 0.6.0

package/templates/README.md

@@ -0,0 +1,228 @@
+# SDL-MCP Plugin Templates
+
+<div align="right">
+<details>
+<summary><strong>Docs Navigation</strong></summary>
+
+- [SDL-MCP Overview](../README.md)
+- [Documentation Hub](../docs/README.md)
+  - [Getting Started](../docs/getting-started.md)
+  - [Plugin SDK Author Guide](../docs/PLUGIN_SDK_AUTHOR_GUIDE.md)
+  - [Plugin SDK Security](../docs/PLUGIN_SDK_SECURITY.md)
+- [Templates (this page)](./README.md)
+- [Plugin Template README](./plugin-template/README.md)
+
+</details>
+</div>
+
+Templates and scaffolding for creating SDL-MCP adapter plugins.
+
+## Available Templates
+
+### plugin-template
+
+A complete template for creating a new language adapter plugin.
+
+**Features**:
+
+- Pre-configured TypeScript setup
+- Base adapter implementation
+- Sample extraction logic (regex-based)
+- Test suite template
+- Package.json configuration
+- Comprehensive README
+
+**Use when**:
+
+- Creating a new language adapter
+- Need a starting point for custom adapters
+- Want to follow SDL-MCP plugin conventions
+
+**Quick Start**:
+
+```bash
+# Copy template
+cp -r templates/plugin-template my-lang-plugin
+cd my-lang-plugin
+
+# Customize and build
+npm install
+npm run build
+
+# Register in SDL-MCP
+# Add to config/sdlmcp.config.json:
+{
+  "plugins": {
+    "paths": ["./my-lang-plugin/dist/index.js"]
+  }
+}
+```
+
+See [plugin-template/README.md](./plugin-template/README.md) for detailed instructions.
+
+## Template Structure
+
+```text
+templates/
+|-- plugin-template/        # Full plugin template
+|   |-- package.json        # NPM configuration
+|   |-- tsconfig.json       # TypeScript configuration
+|   |-- index.ts            # Plugin implementation
+|   |-- README.md           # Plugin documentation
+|   |-- LICENSE             # MIT license
+|   `-- test/               # Test suite
+|       `-- plugin.test.ts
+`-- README.md               # This file
+```
+
+## Using Templates
+
+### 1. Copy Template
+
+```bash
+# From SDL-MCP repository
+cp -r templates/plugin-template my-plugin
+cd my-plugin
+```
+
+### 2. Customize
+
+Edit the following files:
+
+- `package.json`: Update name, description, author
+- `index.ts`: Replace placeholder code with your adapter
+- `README.md`: Update documentation for your language
+- `test/plugin.test.ts`: Add language-specific tests
+
+### 3. Build
+
+```bash
+npm install
+npm run build
+```
+
+### 4. Test
+
+```bash
+npm test
+```
+
+### 5. Publish (optional)
+
+```bash
+npm publish
+```
+
+## Customization Guide
+
+### Minimal Changes Required
+
+1. **Update plugin metadata** in `index.ts`:
+
+   ```typescript
+   export const manifest = {
+     name: "sdl-mcp-YOURLANG-plugin",
+     adapters: [
+       {
+         extension: ".yourlang",
+         languageId: "yourlang",
+       },
+     ],
+   };
+   ```
+
+2. **Update adapter class** in `index.ts`:
+
+   ```typescript
+   class YourLangAdapter extends BaseAdapter {
+     languageId = "yourlang" as const;
+     fileExtensions = [".yourlang"] as const;
+   }
+   ```
+
+3. **Implement extraction logic**:
+   - Replace regex patterns in `extractSymbols()`
+   - Replace regex patterns in `extractImports()`
+   - Replace regex patterns in `extractCalls()`
+
+### Advanced Customization
+
+For complex languages, consider:
+
+1. **Use Tree-sitter grammars**:
+
+   ```typescript
+   const parser = this.getParser();
+   const query = parser.getLanguage().query(`
+     (function_declaration name: (_) @name)
+   `);
+   ```
+
+2. **Add language-specific metadata**:
+
+   ```typescript
+   metadata: {
+     visibility: "public",
+     async: false,
+     params: [...],
+     returns: "string",
+   }
+   ```
+
+3. **Handle language-specific features**:
+   - Generics/templates
+   - Decorators/attributes
+   - Macros/preprocessor directives
+   - Custom syntax
+
+## Template vs Example
+
+| Feature       | Template                       | Example                        |
+| ------------- | ------------------------------ | ------------------------------ |
+| Purpose       | Starting point for new plugins | Demonstration of plugin system |
+| Complexity    | Minimal, easy to customize     | Functional, production-ready   |
+| Documentation | Inline comments, guide         | Comprehensive README           |
+| Tests         | Template test suite            | Integration tests              |
+| Language      | Placeholder (mylang)           | Hypothetical (example-lang)    |
+
+**Use the template** when creating your own plugin.
+
+**Use the example** when learning the plugin system.
+
+## Next Steps
+
+After using a template:
+
+1. **Read the author guide**: [PLUGIN_SDK_AUTHOR_GUIDE.md](../docs/PLUGIN_SDK_AUTHOR_GUIDE.md)
+2. **Review security docs**: [PLUGIN_SDK_SECURITY.md](../docs/PLUGIN_SDK_SECURITY.md)
+3. **Study the example**: [examples/example-plugin/](../examples/example-plugin/)
+4. **Run integration tests**: `npm run test:integration`
+
+## Support
+
+For help with templates:
+
+- Check the [Author Guide](../docs/PLUGIN_SDK_AUTHOR_GUIDE.md)
+- Review the [Example Plugin](../examples/example-plugin/)
+- Check [Troubleshooting](../docs/PLUGIN_SDK_AUTHOR_GUIDE.md#troubleshooting)
+- Open an issue on GitHub
+
+## Contributing
+
+Have suggestions for improving templates? Contributions welcome:
+
+1. Fork the repository
+2. Improve the template
+3. Add tests for new features
+4. Submit a pull request
+
+## License
+
+All templates are licensed under MIT.
+
+## See Also
+
+- [SDL-MCP README](../README.md)
+- [Plugin SDK Implementation Summary](../docs/PLUGIN_SDK_IMPLEMENTATION.md)
+- [Example Plugin](../examples/example-plugin/)
+

package/templates/claude-code.json

@@ -0,0 +1,54 @@
+{
+  "_comment": "Claude Code MCP Configuration Template for SDL-MCP",
+  "_documentation": {
+    "purpose": "Configure SDL-MCP as an MCP server for Claude Code",
+    "placement": "Copy to ~/.claude/claude_desktop_config.json or add to existing mcpServers",
+    "windowsNotes": {
+      "paths": "Use forward slashes (/) or escaped backslashes (\\\\)",
+      "npx": "npx works cross-platform. For global install, use 'node' with full path",
+      "environment": "SDL_CONFIG_PATH or SDL_CONFIG must be set to point to your sdlmcp.config.json"
+    },
+    "quoting": {
+      "powerShell": "Single quotes work for paths, double quotes for variable expansion",
+      "cmd": "Use double quotes for all paths with spaces"
+    },
+    "workspaceFolder": {
+      "description": "Replaced by Claude Code with the current workspace root",
+      "windows": "Resolves to forward-slash path on all platforms"
+    }
+  },
+  "mcpServers": {
+    "sdl-mcp": {
+      "command": "npx",
+      "args": ["sdl-mcp"],
+      "env": {
+        "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json",
+        "_comment_env": "Alternative: Set SDL_CONFIG_PATH if you prefer environment variable name"
+      }
+    }
+  },
+  "_alternative_global_install": {
+    "description": "If you installed SDL-MCP globally with 'npm install -g sdl-mcp':",
+    "mcpServers": {
+      "sdl-mcp": {
+        "command": "sdl-mcp",
+        "args": [],
+        "env": {
+          "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+        }
+      }
+    }
+  },
+  "_alternative_windows_direct_node": {
+    "description": "Windows alternative using direct Node invocation (if npx is unavailable):",
+    "mcpServers": {
+      "sdl-mcp": {
+        "command": "node",
+        "args": ["F:/path/to/sdl-mcp/dist/main.js"],
+        "env": {
+          "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+        }
+      }
+    }
+  }
+}

package/templates/codex.json

@@ -0,0 +1,55 @@
+{
+  "_comment": "Codex CLI MCP Configuration Template for SDL-MCP",
+  "_documentation": {
+    "purpose": "Configure SDL-MCP as an MCP server for Codex CLI",
+    "placement": "Add to Codex MCP servers configuration",
+    "windowsNotes": {
+      "paths": "Use forward slashes (/) or escaped backslashes (\\\\)",
+      "npx": "npx works cross-platform. For global install, use 'sdl-mcp' directly",
+      "environment": "SDL_CONFIG_PATH or SDL_CONFIG must point to sdlmcp.config.json"
+    },
+    "quoting": {
+      "cmd": "Use double quotes for paths with spaces, no single quotes",
+      "powershell": "Single quotes work, but cmd is more portable for cross-platform configs"
+    },
+    "workspaceFolder": {
+      "description": "Codex expands ${workspaceFolder} to current directory",
+      "windows": "Resolves correctly on Windows with forward slashes"
+    }
+  },
+  "mcpServers": {
+    "sdl-mcp": {
+      "command": "npx",
+      "args": ["-y", "sdl-mcp"],
+      "env": {
+        "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+      }
+    }
+  },
+  "_alternative_global_install": {
+    "description": "If globally installed with 'npm install -g sdl-mcp':",
+    "mcpServers": {
+      "sdl-mcp": {
+        "command": "sdl-mcp",
+        "args": [],
+        "env": {
+          "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+        }
+      }
+    }
+  },
+  "_windows_specific": {
+    "description": "Windows-specific notes for cmd.exe",
+    "notes": [
+      "Ensure Node.js is in PATH",
+      "If using custom paths, use double backslashes: C:\\\\Users\\\\name\\\\.nvm\\\\versions\\\\node\\\\node.exe",
+      "SDL_CONFIG path uses forward slashes for cross-platform compatibility",
+      "If workspaceFolder has spaces, Codex CLI handles quoting automatically"
+    ]
+  },
+  "_troubleshooting": {
+    "npx_fails": "If npx fails, try 'npm config set script-shell pwsh' (PowerShell) or use global install",
+    "path_not_found": "Verify SDL_CONFIG path exists and is accessible",
+    "permissions": "Ensure Node.js has read access to config file and database path"
+  }
+}

package/templates/gemini.json

@@ -0,0 +1,66 @@
+{
+  "_comment": "Gemini CLI MCP Configuration Template for SDL-MCP",
+  "_documentation": {
+    "purpose": "Configure SDL-MCP as an MCP server for Gemini CLI",
+    "placement": "Add to Gemini MCP servers configuration file",
+    "windowsNotes": {
+      "paths": "Gemini CLI expects forward slashes (/) or escaped backslashes (\\\\)",
+      "npx": "npx is cross-platform. Use 'sdl-mcp' for global install",
+      "environment": "SDL_CONFIG or SDL_CONFIG_PATH required for configuration"
+    },
+    "quoting": {
+      "powershell": "Use single quotes for literal paths, double quotes with $ for variables",
+      "cmd": "Double quotes only; cmd does not support single quotes for strings"
+    },
+    "workspaceFolder": {
+      "description": "Gemini CLI replaces ${workspaceFolder} with workspace root",
+      "windows": "Always resolves to forward-slash normalized path"
+    }
+  },
+  "mcpServers": {
+    "sdl-mcp": {
+      "command": "npx",
+      "args": ["sdl-mcp"],
+      "env": {
+        "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+      }
+    }
+  },
+  "_alternative_global_install": {
+    "description": "For global installation (npm install -g sdl-mcp):",
+    "mcpServers": {
+      "sdl-mcp": {
+        "command": "sdl-mcp",
+        "args": [],
+        "env": {
+          "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+        }
+      }
+    }
+  },
+  "_windows_path_examples": {
+    "description": "Example paths for Windows environments",
+    "configPath": {
+      "forward_slash": "${workspaceFolder}/sdlmcp.config.json",
+      "escaped_backslash": "C:\\\\Users\\\\username\\\\project\\\\sdlmcp.config.json"
+    },
+    "nodePath": {
+      "if_needed": "C:\\\\Program Files\\\\nodejs\\\\node.exe"
+    }
+  },
+  "_shell_specific_quoting": {
+    "cmd": {
+      "rule": "Always use double quotes for paths",
+      "example": "\"C:\\Users\\name\\project\\sdlmcp.config.json\""
+    },
+    "powershell": {
+      "rule": "Single quotes for literals, double quotes with $var for expansion",
+      "example": "'C:/Users/name/project/sdlmcp.config.json'"
+    }
+  },
+  "_troubleshooting": {
+    "npx_hangs": "Try adding -y flag: npx -y sdl-mcp",
+    "permission_denied": "Check file permissions for config and database",
+    "path_resolution": "Verify workspaceFolder is set correctly in Gemini CLI"
+  }
+}

package/templates/opencode.json

@@ -0,0 +1,90 @@
+{
+  "_comment": "Opencode CLI MCP Configuration Template for SDL-MCP",
+  "_documentation": {
+    "purpose": "Configure SDL-MCP as an MCP server for Opencode CLI",
+    "placement": "Add to Opencode MCP servers configuration",
+    "windowsNotes": {
+      "paths": "Opencode normalizes to forward slashes automatically",
+      "npx": "npx works cross-platform. Use 'sdl-mcp' for global install",
+      "environment": "SDL_CONFIG_PATH or SDL_CONFIG must point to sdlmcp.config.json"
+    },
+    "quoting": {
+      "cmd": "Double quotes only for all paths",
+      "powershell": "Single or double quotes both work",
+      "opencode_handling": "Opencode CLI handles quoting automatically when using ${workspaceFolder}"
+    },
+    "workspaceFolder": {
+      "description": "Opencode replaces ${workspaceFolder} with detected workspace root",
+      "detection": "Auto-detects from .git directory, package.json, or current directory",
+      "windows": "Normalizes Windows paths to forward slashes"
+    }
+  },
+  "mcpServers": {
+    "sdl-mcp": {
+      "command": "npx",
+      "args": ["sdl-mcp"],
+      "env": {
+        "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+      }
+    }
+  },
+  "_alternative_global_install": {
+    "description": "After global install (npm install -g sdl-mcp):",
+    "mcpServers": {
+      "sdl-mcp": {
+        "command": "sdl-mcp",
+        "args": [],
+        "env": {
+          "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+        }
+      }
+    }
+  },
+  "_workspace_detection": {
+    "description": "How Opencode detects workspaceFolder",
+    "methods": [
+      "Git repository root (.git directory)",
+      "Node.js project root (package.json)",
+      "Current working directory",
+      "Manually specified via --workspace flag"
+    ]
+  },
+  "_windows_path_handling": {
+    "description": "Opencode CLI specific Windows path handling",
+    "normalization": "All paths normalized to forward slashes internally",
+    "examples": {
+      "input": "C:\\Users\\name\\project",
+      "normalized": "C:/Users/name/project",
+      "config_file": "${workspaceFolder}/sdlmcp.config.json resolves to C:/Users/name/project/sdlmcp.config.json"
+    }
+  },
+  "_slash_normalization": {
+    "description": "SDL-MCP path normalization (server-side)",
+    "behavior": "Server normalizes all paths using path utilities",
+    "storage": "Paths stored with forward slashes in database",
+    "resolution": "Resolved to OS-specific paths on read"
+  },
+  "_troubleshooting": {
+    "workspace_not_found": "Run from within a valid workspace or specify --workspace",
+    "config_missing": "Ensure sdlmcp.config.json exists at SDL_CONFIG path",
+    "path_case": "Windows paths are case-insensitive, but forward slashes required in env vars",
+    "npx_timeout": "If npx times out, try global install or use node with full path"
+  },
+  "_complete_windows_example": {
+    "description": "Full example for Windows with explicit paths",
+    "setup": {
+      "1": "npm install -g sdl-mcp",
+      "2": "Create sdlmcp.config.json in your project root",
+      "3": "Run opencode from project directory"
+    },
+    "mcpServers": {
+      "sdl-mcp": {
+        "command": "sdl-mcp",
+        "args": [],
+        "env": {
+          "SDL_CONFIG": "${workspaceFolder}/sdlmcp.config.json"
+        }
+      }
+    }
+  }
+}

package/templates/plugin-template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+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.