sdl-mcp 0.6.0

package/templates/plugin-template/README.md

@@ -0,0 +1,309 @@
+# MyLang Plugin for SDL-MCP
+
+<div align="right">
+<details>
+<summary><strong>Docs Navigation</strong></summary>
+
+- [SDL-MCP Overview](../../README.md)
+- [Documentation Hub](../../docs/README.md)
+  - [Plugin SDK Author Guide](../../docs/PLUGIN_SDK_AUTHOR_GUIDE.md)
+  - [Plugin SDK Security](../../docs/PLUGIN_SDK_SECURITY.md)
+- [Templates Index](../README.md)
+- [Plugin Template (this page)](./README.md)
+- [Example Plugin](../../examples/example-plugin/README.md)
+
+</details>
+</div>
+
+A template adapter plugin for SDL-MCP. Customize this to add support for your language.
+
+## Quick Start
+
+```bash
+# 1. Copy this template
+cp -r templates/plugin-template my-lang-plugin
+cd my-lang-plugin
+
+# 2. Customize package.json
+# Update name, description, author fields
+
+# 3. Customize index.ts
+# Replace "mylang" with your language name
+# Implement extraction logic for your language
+
+# 4. Install and build
+npm install
+npm run build
+
+# 5. Register in SDL-MCP config
+# Add to config/sdlmcp.config.json:
+{
+  "plugins": {
+    "paths": ["./my-lang-plugin/dist/index.js"],
+    "enabled": true
+  }
+}
+
+# 6. Test
+sdl-mcp index
+```
+
+## Customization Guide
+
+### 1. Update Plugin Metadata
+
+Edit `manifest` in `index.ts`:
+
+```typescript
+export const manifest = {
+  name: "sdl-mcp-YOURLANG-plugin", // Change this
+  version: "1.0.0",
+  apiVersion: "1.0.0",
+  description: "YOUR LANG adapter plugin", // Change this
+  author: "Your Name", // Change this
+  license: "MIT", // Change if needed
+  adapters: [
+    {
+      extension: ".yourlang", // Change this
+      languageId: "yourlang", // Change this
+    },
+  ],
+};
+```
+
+### 2. Update Adapter Class
+
+Edit `MyLangAdapter` in `index.ts`:
+
+```typescript
+class YourLangAdapter extends BaseAdapter {
+  languageId = "yourlang" as const; // Change this
+  fileExtensions = [".yourlang"] as const; // Change this
+
+  // Implement extraction methods for your language
+}
+```
+
+### 3. Implement Extraction Logic
+
+Replace the placeholder extraction methods with your language-specific logic:
+
+#### For Simple Languages (Regex-based)
+
+```typescript
+extractSymbols(_tree: any, content: string, filePath: string): ExtractedSymbol[] {
+  const symbols: ExtractedSymbol[] = [];
+
+  const lines = content.split("\n");
+
+  lines.forEach((line, index) => {
+    // Match function definitions
+    const funcMatch = line.match(/YOUR_REGEX_HERE/);
+    if (funcMatch) {
+      symbols.push({
+        id: `${filePath}:fn:${funcMatch[1]}`,
+        name: funcMatch[1],
+        kind: "function",
+        filePath,
+        range: {
+          startLine: index + 1,
+          startCol: line.indexOf(funcMatch[1]),
+          endLine: index + 1,
+          endCol: line.indexOf(funcMatch[1]) + funcMatch[1].length,
+        },
+        parentId: null,
+        metadata: {},
+      });
+    }
+  });
+
+  return symbols;
+}
+```
+
+#### For Complex Languages (Tree-sitter-based)
+
+```typescript
+import { getParser } from "sdl-mcp/dist/indexer/treesitter/grammarLoader.js";
+
+class YourLangAdapter extends BaseAdapter {
+  languageId = "yourlang" as const;
+  fileExtensions = [".yourlang"] as const;
+
+  extractSymbols(
+    tree: any,
+    content: string,
+    filePath: string,
+  ): ExtractedSymbol[] {
+    const symbols: ExtractedSymbol[] = [];
+
+    if (!tree) {
+      return symbols;
+    }
+
+    const parser = this.getParser();
+    if (!parser) {
+      return symbols;
+    }
+
+    const language = parser.getLanguage();
+
+    try {
+      const query = language.query(`
+        (function_declaration name: (identifier) @name)
+        (class_declaration name: (identifier) @name)
+      `);
+
+      const captures = query.captures(tree.rootNode);
+
+      for (const [node, name] of captures) {
+        if (name === "name") {
+          symbols.push({
+            id: `${filePath}:${node.text}`,
+            name: node.text,
+            kind:
+              node.parent?.type === "function_declaration"
+                ? "function"
+                : "class",
+            filePath,
+            range: this.extractRange(node),
+            parentId: null,
+            metadata: {},
+          });
+        }
+      }
+    } catch (error) {
+      console.error(`Query error in ${filePath}:`, error);
+    }
+
+    return symbols;
+  }
+}
+```
+
+### 4. Update package.json
+
+```json
+{
+  "name": "sdl-mcp-yourlang-plugin",
+  "version": "1.0.0",
+  "description": "YourLang adapter plugin for SDL-MCP",
+  "author": "Your Name <your.email@example.com>",
+  "keywords": ["sdl-mcp", "plugin", "adapter", "yourlang"]
+}
+```
+
+## File Structure
+
+```text
+my-lang-plugin/
+|-- package.json          # NPM package metadata
+|-- tsconfig.json         # TypeScript configuration
+|-- index.ts              # Plugin implementation
+|-- README.md             # Plugin documentation (this file)
+|-- LICENSE               # License file
+`-- dist/                 # Compiled output (generated)
+    |-- index.js
+    |-- index.d.ts
+    `-- index.js.map
+```
+
+## Testing
+
+Create test files with your language's extension:
+
+```yourlang
+// test.mylang
+import "stdlib"
+
+function greet(name: string) {
+  print("Hello, " + name + "!");
+}
+
+class Calculator {
+  function add(a: number, b: number): number {
+    return a + b;
+  }
+}
+
+function main() {
+  greet("World");
+  let calc = Calculator();
+  calc.add(5, 3);
+}
+```
+
+Run SDL-MCP indexing:
+
+```bash
+sdl-mcp index
+```
+
+Check logs for:
+
+```
+Plugin loaded successfully: your-lang-plugin@1.0.0
+Indexed test.mylang: 3 symbols, 1 imports, 3 calls
+```
+
+## Publishing
+
+### Publish to NPM
+
+```bash
+# 1. Login to NPM
+npm login
+
+# 2. Build plugin
+npm run build
+
+# 3. Publish
+npm publish --access public
+
+# 4. Verify
+npm view sdl-mcp-yourlang-plugin
+```
+
+### Publish to Private Registry
+
+```bash
+# 1. Configure registry
+npm config set registry https://npm.yourcompany.com
+
+# 2. Publish
+npm publish
+
+# 3. Users install from your registry
+npm install --registry https://npm.yourcompany.com sdl-mcp-yourlang-plugin
+```
+
+## Documentation
+
+For more detailed information:
+
+- [Plugin SDK Author Guide](../../docs/PLUGIN_SDK_AUTHOR_GUIDE.md)
+- [Plugin SDK Security](../../docs/PLUGIN_SDK_SECURITY.md)
+- [Example Plugin](../../examples/example-plugin/README.md)
+- [SDL-MCP README](../../README.md)
+
+## Support
+
+For issues or questions:
+
+- Check the [troubleshooting guide](../../docs/PLUGIN_SDK_AUTHOR_GUIDE.md#troubleshooting)
+- Review the [Example Plugin](../../examples/example-plugin/README.md)
+- Open an issue on the SDL-MCP repository
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork this template
+2. Customize for your language
+3. Add tests
+4. Submit a pull request
+

package/templates/plugin-template/index.ts

@@ -0,0 +1,160 @@
+import { BaseAdapter } from "sdl-mcp/dist/indexer/adapter/BaseAdapter.js";
+import type {
+  LanguageAdapter,
+  ExtractedSymbol,
+  ExtractedImport,
+  ExtractedCall,
+} from "sdl-mcp/dist/indexer/adapter/LanguageAdapter.js";
+import type {
+  AdapterPlugin,
+  PluginAdapter,
+} from "sdl-mcp/dist/indexer/adapter/plugin/types.js";
+
+const PLUGIN_API_VERSION = "1.0.0";
+
+export const manifest = {
+  name: "sdl-mcp-mylang-plugin",
+  version: "1.0.0",
+  apiVersion: PLUGIN_API_VERSION,
+  description: "MyLang adapter plugin for SDL-MCP",
+  author: "Your Name",
+  license: "MIT",
+  adapters: [
+    {
+      extension: ".mylang",
+      languageId: "mylang",
+    },
+  ],
+};
+
+class MyLangAdapter extends BaseAdapter {
+  languageId = "mylang" as const;
+  fileExtensions = [".mylang"] as const;
+
+  extractSymbols(
+    _tree: any,
+    content: string,
+    filePath: string,
+  ): ExtractedSymbol[] {
+    const symbols: ExtractedSymbol[] = [];
+
+    const lines = content.split("\n");
+
+    lines.forEach((line, index) => {
+      const funcMatch = line.match(/function\s+(\w+)\s*\(/);
+      if (funcMatch) {
+        symbols.push({
+          id: `${filePath}:fn:${funcMatch[1]}`,
+          name: funcMatch[1],
+          kind: "function",
+          filePath,
+          range: {
+            startLine: index + 1,
+            startCol: line.indexOf(funcMatch[1]),
+            endLine: index + 1,
+            endCol: line.indexOf(funcMatch[1]) + funcMatch[1].length,
+          },
+          parentId: null,
+          metadata: {},
+        });
+      }
+
+      const classMatch = line.match(/class\s+(\w+)/);
+      if (classMatch) {
+        symbols.push({
+          id: `${filePath}:class:${classMatch[1]}`,
+          name: classMatch[1],
+          kind: "class",
+          filePath,
+          range: {
+            startLine: index + 1,
+            startCol: line.indexOf(classMatch[1]),
+            endLine: index + 1,
+            endCol: line.indexOf(classMatch[1]) + classMatch[1].length,
+          },
+          parentId: null,
+          metadata: {},
+        });
+      }
+    });
+
+    return symbols;
+  }
+
+  extractImports(
+    _tree: any,
+    content: string,
+    filePath: string,
+  ): ExtractedImport[] {
+    const imports: ExtractedImport[] = [];
+
+    const lines = content.split("\n");
+
+    lines.forEach((line, index) => {
+      const importMatch = line.match(/import\s+"(.+)"/);
+      if (importMatch) {
+        imports.push({
+          id: `${filePath}:import:${index}`,
+          filePath,
+          range: {
+            startLine: index + 1,
+            startCol: line.indexOf("import"),
+            endLine: index + 1,
+            endCol: line.length,
+          },
+          moduleName: importMatch[1],
+          symbols: [],
+        });
+      }
+    });
+
+    return imports;
+  }
+
+  extractCalls(
+    _tree: any,
+    content: string,
+    filePath: string,
+    extractedSymbols: ExtractedSymbol[],
+  ): ExtractedCall[] {
+    const calls: ExtractedCall[] = [];
+
+    const lines = content.split("\n");
+
+    lines.forEach((line, index) => {
+      const callMatch = line.match(/(\w+)\s*\(/);
+      if (callMatch) {
+        const functionName = callMatch[1];
+        const symbol = extractedSymbols.find((s) => s.name === functionName);
+
+        if (symbol) {
+          calls.push({
+            id: `${filePath}:call:${index}:${functionName}`,
+            filePath,
+            range: {
+              startLine: index + 1,
+              startCol: line.indexOf(functionName),
+              endLine: index + 1,
+              endCol: line.indexOf(functionName) + functionName.length,
+            },
+            targetSymbolId: symbol.id,
+          });
+        }
+      }
+    });
+
+    return calls;
+  }
+}
+
+export async function createAdapters(): Promise<PluginAdapter[]> {
+  return [
+    {
+      extension: ".mylang",
+      languageId: "mylang",
+      factory: () => new MyLangAdapter(),
+    },
+  ];
+}
+
+export default { manifest, createAdapters };

package/templates/plugin-template/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "sdl-mcp-mylang-plugin",
+  "version": "1.0.0",
+  "description": "MyLang adapter plugin for SDL-MCP",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sdl-mcp",
+    "plugin",
+    "adapter",
+    "mylang"
+  ],
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "sdl-mcp": "*"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/plugin-template/test/plugin.test.ts

@@ -0,0 +1,186 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { MyLangAdapter } from "../dist/index.js";
+
+describe("MyLang Plugin Tests", () => {
+  const adapter = new MyLangAdapter();
+
+  describe("Metadata", () => {
+    it("should have correct language ID", () => {
+      assert.strictEqual(adapter.languageId, "mylang");
+    });
+
+    it("should have correct file extensions", () => {
+      assert.ok(adapter.fileExtensions.includes(".mylang"));
+    });
+  });
+
+  describe("Symbol Extraction", () => {
+    it("should extract functions", () => {
+      const content = `function greet(name: string) {
+  print("Hello, " + name + "!");
+}`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+
+      const greet = symbols.find((s) => s.name === "greet");
+      assert.ok(greet, "Should extract greet function");
+      assert.strictEqual(greet.kind, "function");
+      assert.strictEqual(greet.filePath, "test.mylang");
+      assert.ok(greet.range, "Should have range information");
+    });
+
+    it("should extract classes", () => {
+      const content = `class Calculator {
+  function add(a: number, b: number): number {
+    return a + b;
+  }
+}`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+
+      const calculator = symbols.find((s) => s.name === "Calculator");
+      assert.ok(calculator, "Should extract Calculator class");
+      assert.strictEqual(calculator.kind, "class");
+    });
+
+    it("should handle empty content", () => {
+      const content = "";
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+
+      assert.strictEqual(symbols.length, 0);
+    });
+
+    it("should extract multiple symbols", () => {
+      const content = `function func1() {}
+function func2() {}
+class MyClass {}`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+
+      assert.ok(symbols.length >= 3, "Should extract multiple symbols");
+      assert.ok(symbols.some((s) => s.name === "func1"));
+      assert.ok(symbols.some((s) => s.name === "func2"));
+      assert.ok(symbols.some((s) => s.name === "MyClass"));
+    });
+  });
+
+  describe("Import Extraction", () => {
+    it("should extract imports", () => {
+      const content = `import "stdlib"
+import "mylib/utils"`;
+      const imports = adapter.extractImports(null, content, "test.mylang");
+
+      assert.strictEqual(imports.length, 2);
+      assert.ok(imports.some((i) => i.moduleName === "stdlib"));
+      assert.ok(imports.some((i) => i.moduleName === "mylib/utils"));
+    });
+
+    it("should handle empty imports", () => {
+      const content = "";
+      const imports = adapter.extractImports(null, content, "test.mylang");
+
+      assert.strictEqual(imports.length, 0);
+    });
+
+    it("should extract import with correct range", () => {
+      const content = `import "stdlib"`;
+      const imports = adapter.extractImports(null, content, "test.mylang");
+
+      assert.strictEqual(imports.length, 1);
+      assert.strictEqual(imports[0].moduleName, "stdlib");
+      assert.strictEqual(imports[0].range.startLine, 1);
+      assert.ok(imports[0].range.endCol > imports[0].range.startCol);
+    });
+  });
+
+  describe("Call Extraction", () => {
+    it("should extract function calls", () => {
+      const content = `function test() {}
+test()`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+      const calls = adapter.extractCalls(null, content, "test.mylang", symbols);
+
+      const testCall = calls.find((c) => c.targetSymbolId.includes("test"));
+      assert.ok(testCall, "Should extract call to test function");
+      assert.strictEqual(testCall.filePath, "test.mylang");
+      assert.ok(testCall.range, "Should have range information");
+    });
+
+    it("should extract multiple calls", () => {
+      const content = `function func1() {}
+function func2() {}
+func1()
+func2()`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+      const calls = adapter.extractCalls(null, content, "test.mylang", symbols);
+
+      assert.ok(calls.length >= 2, "Should extract multiple calls");
+      assert.ok(calls.some((c) => c.targetSymbolId.includes("func1")));
+      assert.ok(calls.some((c) => c.targetSymbolId.includes("func2")));
+    });
+
+    it("should not extract calls to undefined symbols", () => {
+      const content = `undefinedFunction()`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+      const calls = adapter.extractCalls(null, content, "test.mylang", symbols);
+
+      assert.strictEqual(
+        calls.length,
+        0,
+        "Should not extract calls to undefined symbols",
+      );
+    });
+  });
+
+  describe("Graph Structure", () => {
+    it("should maintain valid symbol IDs", () => {
+      const content = `function test() {}`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+
+      for (const symbol of symbols) {
+        assert.ok(symbol.id, "Symbol should have ID");
+        assert.ok(
+          symbol.id.includes("test.mylang"),
+          "ID should include file path",
+        );
+        assert.ok(symbol.id.includes("test"), "ID should include symbol name");
+      }
+    });
+
+    it("should maintain valid call references", () => {
+      const content = `function test() {}
+test()`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+      const calls = adapter.extractCalls(null, content, "test.mylang", symbols);
+
+      for (const call of calls) {
+        assert.ok(call.targetSymbolId, "Call should have targetSymbolId");
+        const targetSymbol = symbols.find((s) => s.id === call.targetSymbolId);
+        assert.ok(targetSymbol, "Call should reference existing symbol");
+      }
+    });
+
+    it("should extract complete graph", () => {
+      const content = `import "stdlib"
+
+function helper() {
+  return 42
+}
+
+function main() {
+  helper()
+  print("Done")
+}`;
+      const symbols = adapter.extractSymbols(null, content, "test.mylang");
+      const imports = adapter.extractImports(null, content, "test.mylang");
+      const calls = adapter.extractCalls(null, content, "test.mylang", symbols);
+
+      assert.ok(symbols.length > 0, "Should have symbols");
+      assert.ok(imports.length > 0, "Should have imports");
+      assert.ok(calls.length > 0, "Should have calls");
+
+      assert.ok(symbols.some((s) => s.name === "helper"));
+      assert.ok(symbols.some((s) => s.name === "main"));
+      assert.ok(imports.some((i) => i.moduleName === "stdlib"));
+      assert.ok(calls.some((c) => c.targetSymbolId.includes("helper")));
+    });
+  });
+});

package/templates/plugin-template/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["index.ts", "test/**/*.test.ts"],
+  "exclude": ["node_modules", "dist"]
+}