@netoalmanca/advpl-sensei 1.1.0

package/dist/index.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Estrutura: dist/index.js -> mcp-server/
+const MCP_ROOT = path.resolve(__dirname, "..");
+const server = new Server({
+    name: "advpl-sensei",
+    version: "1.1.0",
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+        prompts: {},
+    },
+});
+/**
+ * Resources
+ */
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const skillsDir = path.join(MCP_ROOT, "skills");
+    const resources = [];
+    async function walk(dir) {
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    await walk(fullPath);
+                }
+                else if (entry.name.endsWith(".md")) {
+                    const relPath = path.relative(skillsDir, fullPath);
+                    resources.push({
+                        uri: `mcp://advpl/skills/${relPath}`,
+                        name: relPath,
+                        mimeType: "text/markdown",
+                    });
+                }
+            }
+        }
+        catch (e) { }
+    }
+    await walk(skillsDir);
+    return { resources };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = new URL(request.params.uri);
+    const relPath = uri.pathname.replace("/advpl/skills/", "");
+    const filePath = path.join(MCP_ROOT, "skills", relPath);
+    const text = await fs.readFile(filePath, "utf-8");
+    return {
+        contents: [{ uri: request.params.uri, mimeType: "text/markdown", text }],
+    };
+});
+/**
+ * Tools
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const commandsDir = path.join(MCP_ROOT, "commands");
+    const tools = [];
+    try {
+        const files = await fs.readdir(commandsDir);
+        for (const file of files) {
+            if (file.endsWith(".md")) {
+                const name = file.replace(".md", "");
+                const content = await fs.readFile(path.join(commandsDir, file), "utf-8");
+                const descMatch = content.match(/description: (.*)/);
+                tools.push({
+                    name: `advpl_${name}`,
+                    description: descMatch ? descMatch[1] : `Command ${name}`,
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            prompt: { type: "string" },
+                            args: { type: "string" },
+                        },
+                        required: ["prompt"],
+                    },
+                });
+            }
+        }
+    }
+    catch (e) { }
+    return { tools };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const name = request.params.name.replace("advpl_", "");
+    const filePath = path.join(MCP_ROOT, "commands", `${name}.md`);
+    const instructions = await fs.readFile(filePath, "utf-8");
+    const { prompt, args } = request.params.arguments;
+    return {
+        content: [{
+                type: "text",
+                text: `Tool: ${name}\nContext: ${instructions}\nInput: ${prompt}\nArgs: ${args || ""}`,
+            }],
+    };
+});
+/**
+ * Prompts
+ */
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    const agentsDir = path.join(MCP_ROOT, "agents");
+    const prompts = [];
+    try {
+        const files = await fs.readdir(agentsDir);
+        for (const file of files) {
+            if (file.endsWith(".md")) {
+                const name = file.replace(".md", "");
+                prompts.push({
+                    name: `advpl_agent_${name}`,
+                    description: `Agent ${name}`,
+                    arguments: [{ name: "context", required: false }],
+                });
+            }
+        }
+    }
+    catch (e) { }
+    return { prompts };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const name = request.params.name.replace("advpl_agent_", "");
+    const filePath = path.join(MCP_ROOT, "agents", `${name}.md`);
+    const text = await fs.readFile(filePath, "utf-8");
+    return {
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Role: ${name}\nRules: ${text}\nContext: ${request.params.arguments?.context || ""}`,
+                },
+            }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(() => { });

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@netoalmanca/advpl-sensei",
+  "version": "1.1.0",
+  "description": "MCP Server for ADVPL/TLPP Protheus ecosystem",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "advpl-sensei": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "commands",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.5.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.9",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  }
+}

package/skills/advpl-code-generation/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: advpl-code-generation
+description: Use when creating ADVPL/TLPP code - functions, classes, MVC structures, REST APIs, Web Services, or entry points for TOTVS Protheus
+---
+
+# ADVPL/TLPP Code Generation
+
+## Overview
+
+Patterns and templates for generating clean, standardized ADVPL and TLPP code for TOTVS Protheus. Covers User Functions, classes, MVC, REST APIs, Web Services, and entry points (pontos de entrada).
+
+## When to Use
+
+- Creating new functions (User Function, Static Function)
+- Creating TLPP classes with methods
+- Building MVC structures (Model/View/Controller)
+- Implementing REST API endpoints
+- Writing entry points (pontos de entrada)
+- Creating SOAP Web Services
+- Any new .prw or .tlpp file creation
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| User Function | Module prefix + descriptive name | `FATA001` (Faturamento), `COMA100` (Compras) |
+| Static Function | Descriptive, camelCase or PascalCase | `ValidaCampo`, `GravaRegistro` |
+| Class (TLPP) | PascalCase, suffix with purpose | `PedidoService`, `ClienteController` |
+| Method | camelCase | `getTotal`, `validarDados` |
+| Variable Local | c/n/d/l/a/o prefix + PascalCase | `cNome`, `nTotal`, `dData`, `lOk`, `aItens`, `oObj` |
+| Parameter | Same as variable | `cCodCli`, `nQuantidade` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRIES`, `DEFAULT_TIMEOUT` |
+
+**Type prefixes (Hungarian notation):**
+| Prefix | Type | Example |
+|--------|------|---------|
+| c | Character/String | `cNome`, `cEndereco` |
+| n | Numeric | `nValor`, `nQuantidade` |
+| d | Date | `dEmissao`, `dVencimento` |
+| l | Logical/Boolean | `lOk`, `lContinua` |
+| a | Array | `aItens`, `aCampos` |
+| o | Object | `oModel`, `oView` |
+| b | Code Block | `bBloco`, `bCondic` |
+| x | Indefinido (any) | `xRetorno`, `xParam` |
+
+**Module prefixes:**
+| Prefix | Module |
+|--------|--------|
+| COM | Compras |
+| EST | Estoque |
+| FAT | Faturamento |
+| FIN | Financeiro |
+| CTB | Contabilidade |
+| FIS | Fiscal |
+| GFE | Gestao de Frete |
+| HCM | Capital Humano |
+| MNT | Manutencao de Ativos |
+| PCP | Planejamento e Controle de Producao |
+
+## Mandatory Structure - User Function
+
+Every User Function MUST follow this pattern:
+
+```advpl
+#Include "TOTVS.CH"
+#Include "TopConn.ch"
+
+/*/{Protheus.doc} FATA001
+Descricao breve da funcao
+@type User Function
+@author Nome do Autor
+@since DD/MM/YYYY
+@version 1.0
+@param cParam1, Caractere, Descricao do parametro
+@return lRet, Logico, Retorno da funcao
+@example
+    u_FATA001("001")
+/*/
+User Function FATA001(cParam1)
+    Local lRet := .T.
+    Local cAlias := "SA1"
+
+    // Salva area de trabalho
+    Local aArea := GetArea()
+
+    Begin Sequence
+
+        // Logica principal aqui
+        DbSelectArea(cAlias)
+        DbSetOrder(1)
+
+        If DbSeek(xFilial(cAlias) + cParam1)
+            // Processamento
+        Else
+            lRet := .F.
+            MsgAlert("Registro nao encontrado")
+        EndIf
+
+    Recover Using oError
+        lRet := .F.
+        Conout("Erro em FATA001: " + oError:Description)
+    End Sequence
+
+    // Restaura area
+    RestArea(aArea)
+
+Return lRet
+```
+
+## Variable Scope Rules
+
+| Scope | Keyword | Visibility | Use Case |
+|-------|---------|-----------|----------|
+| Local | `Local` | Current function only | **Always prefer this** |
+| Static | `Static` | Current PRW file | Shared state within file |
+| Private | `Private` | Current function + called functions | **Avoid - use parameters** |
+| Public | `Public` | Entire application | **Never use in new code** |
+
+**Best practice:** Always use `Local`. Pass data via parameters, never via Private/Public.
+
+## Error Handling Pattern
+
+```advpl
+Local oError
+Local bErrorOld := ErrorBlock({|e| oError := e, Break(e)})
+
+Begin Sequence
+
+    // Codigo que pode falhar
+
+Recover Using oError
+    Conout("Erro: " + oError:Description)
+    Conout("Linha: " + cValToChar(oError:GenCode))
+    // Tratar erro ou re-raise
+
+End Sequence
+
+ErrorBlock(bErrorOld)
+```
+
+## Quick Reference - Code Types
+
+| Type | File Extension | Pattern File |
+|------|---------------|-------------|
+| User Function | .prw | Inline above |
+| Static Function | .prw | Inline above (same file as User Function) |
+| Class TLPP | .tlpp | templates-classes.md |
+| MVC | .prw | patterns-mvc.md |
+| REST API | .prw or .tlpp | patterns-rest.md |
+| Ponto de Entrada | .prw | patterns-pontos-entrada.md |
+| Web Service SOAP | .prw | patterns-soap.md |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using Private instead of Local | Always declare as Local, pass via parameters |
+| Not saving/restoring area (GetArea/RestArea) | Always wrap DB operations with area save/restore |
+| Missing error handling | Always use Begin Sequence / Recover / End Sequence |
+| Not closing RecLock | Always use MsUnlock() after RecLock() |
+| Hardcoded branch (filial) | Use xFilial(cAlias) for multi-branch compatibility |
+| Missing TOTVS.CH include | Always include at minimum: #Include "TOTVS.CH" |
+| Not validating function parameters | Check ValType() and empty values at function start |