@sysvv/ai-skill 1.3.0 → 1.4.0

package/dist/core/mcp.js

@@ -1,60 +1,178 @@
 import fs from "fs-extra";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import * as TOML from "smol-toml";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-/** Onde cada agent espera o arquivo de MCP */
-const MCP_TARGETS = {
-    claude: ".mcp.json",
-    codex: ".codex/mcp.json",
-    gemini: ".gemini/mcp.json",
-    copilot: ".github/copilot/mcp.json",
+// ── Targets por agent ───────────────────────────────────────────────────
+const AGENT_MCP_TARGETS = {
+    // ── Claude ──────────────────────────────────────────────────────────
+    // .mcp.json → { mcpServers: { name: { command, args, env } } }
+    claude: {
+        format: "json",
+        file: ".mcp.json",
+        serversKey: "mcpServers",
+        buildServerConfig: (mcp) => {
+            if (mcp.transport === "stdio") {
+                const config = { command: mcp.command };
+                if (mcp.args?.length)
+                    config.args = mcp.args;
+                if (mcp.env && Object.keys(mcp.env).length)
+                    config.env = mcp.env;
+                return config;
+            }
+            const config = { url: mcp.url };
+            if (mcp.headers && Object.keys(mcp.headers).length)
+                config.headers = mcp.headers;
+            if (mcp.env && Object.keys(mcp.env).length)
+                config.env = mcp.env;
+            return config;
+        }
+    },
+    // ── Gemini ──────────────────────────────────────────────────────────
+    // .gemini/settings.json → { mcpServers: { name: { command, args, env, cwd, timeout } } }
+    // Gemini usa "httpUrl" para streamable-http
+    gemini: {
+        format: "json",
+        file: ".gemini/settings.json",
+        serversKey: "mcpServers",
+        buildServerConfig: (mcp) => {
+            const config = {};
+            if (mcp.transport === "stdio") {
+                config.command = mcp.command;
+                if (mcp.args?.length)
+                    config.args = mcp.args;
+                if (mcp.cwd)
+                    config.cwd = mcp.cwd;
+            }
+            else if (mcp.transport === "sse") {
+                config.url = mcp.url;
+                if (mcp.headers && Object.keys(mcp.headers).length)
+                    config.headers = mcp.headers;
+            }
+            else if (mcp.transport === "streamable-http") {
+                config.httpUrl = mcp.url;
+                if (mcp.headers && Object.keys(mcp.headers).length)
+                    config.headers = mcp.headers;
+            }
+            if (mcp.env && Object.keys(mcp.env).length)
+                config.env = mcp.env;
+            if (mcp.timeout)
+                config.timeout = mcp.timeout;
+            return config;
+        }
+    },
+    // ── Codex ───────────────────────────────────────────────────────────
+    // .codex/config.toml → [mcp_servers.<name>]
+    // stdio: command, args, env, cwd
+    // streamable-http: url, bearer_token_env_var, http_headers
+    // extras: startup_timeout_sec, tool_timeout_sec, enabled
+    codex: {
+        format: "toml",
+        file: ".codex/config.toml",
+        buildServerEntry: (mcp) => {
+            const entry = {};
+            if (mcp.transport === "stdio") {
+                entry.command = mcp.command;
+                if (mcp.args?.length)
+                    entry.args = mcp.args;
+                if (mcp.cwd)
+                    entry.cwd = mcp.cwd;
+            }
+            else {
+                // sse e streamable-http → Codex usa "url" para ambos
+                entry.url = mcp.url;
+                if (mcp.headers && Object.keys(mcp.headers).length) {
+                    entry.http_headers = mcp.headers;
+                }
+            }
+            if (mcp.env && Object.keys(mcp.env).length)
+                entry.env = mcp.env;
+            if (mcp.timeout)
+                entry.tool_timeout_sec = Math.ceil(mcp.timeout / 1000);
+            return entry;
+        }
+    },
+    // ── Copilot ─────────────────────────────────────────────────────────
+    // .vscode/mcp.json → { inputs: [], servers: { name: { command, args, env } } }
+    copilot: {
+        format: "json",
+        file: ".vscode/mcp.json",
+        serversKey: "servers",
+        buildServerConfig: (mcp) => {
+            if (mcp.transport === "stdio") {
+                const config = { command: mcp.command };
+                if (mcp.args?.length)
+                    config.args = mcp.args;
+                if (mcp.env && Object.keys(mcp.env).length)
+                    config.env = mcp.env;
+                return config;
+            }
+            const config = { url: mcp.url };
+            if (mcp.headers && Object.keys(mcp.headers).length)
+                config.headers = mcp.headers;
+            if (mcp.env && Object.keys(mcp.env).length)
+                config.env = mcp.env;
+            return config;
+        }
+    },
 };
-/** Resolve o caminho do .mcp.json dentro de /mcps/ */
-function getMcpFilePath(name) {
-    return path.resolve(__dirname, "../../mcps", `${name}.mcp.json`);
+// ── Writers ─────────────────────────────────────────────────────────────
+async function writeJsonTarget(target, targetPath, mcp) {
+    let existing = {};
+    if (await fs.pathExists(targetPath)) {
+        existing = await fs.readJson(targetPath);
+    }
+    // Copilot: garante que "inputs" exista
+    if (target.serversKey === "servers" && !existing.inputs) {
+        existing.inputs = [];
+    }
+    const servers = existing[target.serversKey] ?? {};
+    servers[mcp.name] = target.buildServerConfig(mcp);
+    existing[target.serversKey] = servers;
+    await fs.ensureDir(path.dirname(targetPath));
+    await fs.writeJson(targetPath, existing, { spaces: 2 });
+}
+async function writeTomlTarget(target, targetPath, mcp) {
+    let existing = {};
+    if (await fs.pathExists(targetPath)) {
+        const content = await fs.readFile(targetPath, "utf8");
+        if (content.trim()) {
+            existing = TOML.parse(content);
+        }
+    }
+    const mcpServers = existing.mcp_servers ?? {};
+    mcpServers[mcp.name] = target.buildServerEntry(mcp);
+    existing.mcp_servers = mcpServers;
+    await fs.ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, TOML.stringify(existing), "utf8");
 }
+// ── API pública ─────────────────────────────────────────────────────────
 /** Carrega a definição de um MCP pelo nome */
 export async function loadMcp(name) {
-    const mcpFile = getMcpFilePath(name);
+    const mcpFile = path.resolve(__dirname, "../../mcps", `${name}.mcp.json`);
     if (!(await fs.pathExists(mcpFile))) {
         throw new Error(`MCP "${name}" não encontrado em mcps/${name}.mcp.json`);
     }
     return fs.readJson(mcpFile);
 }
-/** Extrai apenas os campos de server config (sem metadata) */
-function extractServerConfig(mcp) {
-    if (mcp.transport === "stdio") {
-        const config = { command: mcp.command };
-        if (mcp.args?.length)
-            config.args = mcp.args;
-        if (mcp.env && Object.keys(mcp.env).length)
-            config.env = mcp.env;
-        return config;
-    }
-    // sse | streamable-http
-    const config = { url: mcp.url };
-    if (mcp.headers && Object.keys(mcp.headers).length)
-        config.headers = mcp.headers;
-    if (mcp.env && Object.keys(mcp.env).length)
-        config.env = mcp.env;
-    return config;
-}
 /** Escreve o MCP no arquivo alvo do agent, fazendo merge com configs existentes */
 export async function writeMcp(agent, mcp) {
-    const targetFile = MCP_TARGETS[agent];
-    if (!targetFile)
+    const target = AGENT_MCP_TARGETS[agent];
+    if (!target)
         throw new Error(`Agent "${agent}" não tem target de MCP configurado.`);
-    const targetPath = path.resolve(targetFile);
-    let existing = {};
-    if (await fs.pathExists(targetPath)) {
-        existing = await fs.readJson(targetPath);
+    const targetPath = path.resolve(target.file);
+    if (target.format === "json") {
+        await writeJsonTarget(target, targetPath, mcp);
+    }
+    else {
+        await writeTomlTarget(target, targetPath, mcp);
     }
-    const mcpServers = existing.mcpServers ?? {};
-    mcpServers[mcp.name] = extractServerConfig(mcp);
-    await fs.ensureDir(path.dirname(targetPath));
-    await fs.writeJson(targetPath, { ...existing, mcpServers }, { spaces: 2 });
     return targetPath;
 }
+/** Retorna o path do arquivo MCP de um agent */
+export function getMcpTargetPath(agent) {
+    return AGENT_MCP_TARGETS[agent]?.file;
+}
 /** Lista todos os MCPs disponíveis */
 export async function listMcps() {
     const mcpsDir = path.resolve(__dirname, "../../mcps");

package/dist/index.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import { findSkillFiles } from "./core/registry.js";
 import { parseSkillFile } from "./core/frontmatter.js";
 import { loadSkill } from "./core/skill.js";
-import { loadMcp, writeMcp } from "./core/mcp.js";
+import { loadMcp, writeMcp, getMcpTargetPath } from "./core/mcp.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // ── ANSI ────────────────────────────────────────────────────────────────
 const ANSI = {
@@ -178,18 +178,13 @@ async function installSkills(agent) {
 }
 // ── Clear all skills + MCPs ─────────────────────────────────────────────
 async function clearSkills() {
-    const MCP_TARGETS = {
-        claude: ".mcp.json",
-        codex: ".codex/mcp.json",
-        gemini: ".gemini/mcp.json",
-        copilot: ".github/copilot/mcp.json",
-    };
     const found = [];
     for (const [agent, dir] of Object.entries(AGENT_DIRS)) {
         const skillsFull = path.resolve(dir);
-        const mcpFull = path.resolve(MCP_TARGETS[agent]);
+        const mcpTarget = getMcpTargetPath(agent);
+        const mcpFull = mcpTarget ? path.resolve(mcpTarget) : "";
         const hasSkills = await fs.pathExists(skillsFull);
-        const hasMcp = await fs.pathExists(mcpFull);
+        const hasMcp = mcpFull ? await fs.pathExists(mcpFull) : false;
         if (hasSkills || hasMcp) {
             found.push({ agent, skillsDir: skillsFull, mcpFile: mcpFull, hasSkills, hasMcp });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sysvv/ai-skill",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Instale skills de IA direto no seu projeto. Escolha o agent, escolha as skills.",
   "type": "module",
   "bin": {
@@ -30,7 +30,8 @@
   "dependencies": {
     "fs-extra": "^11.3.0",
     "gray-matter": "^4.0.3",
-    "inquirer": "^12.5.2"
+    "inquirer": "^12.5.2",
+    "smol-toml": "^1.6.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/schemas/mcp.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://sysvv.dev/schemas/mcp.schema.json",
   "title": "MCP Server Configuration",
-  "description": "Schema para configuração de servidores MCP (Model Context Protocol). Suporta os transportes stdio, sse e streamable-http.",
+  "description": "Schema para configuração de servidores MCP (Model Context Protocol). Suporta os transportes stdio, sse e streamable-http. Campos opcionais como timeout e cwd são aplicados conforme o suporte de cada agent.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -32,6 +32,10 @@
       "items": { "type": "string" },
       "description": "[stdio] Argumentos passados ao comando."
     },
+    "cwd": {
+      "type": "string",
+      "description": "[stdio] Diretório de trabalho para o processo do servidor."
+    },
     "url": {
       "type": "string",
       "format": "uri",
@@ -46,6 +50,10 @@
       "type": "object",
       "additionalProperties": { "type": "string" },
       "description": "Variáveis de ambiente. Use ${VAR} para referências dinâmicas."
+    },
+    "timeout": {
+      "type": "number",
+      "description": "Timeout da requisição em milissegundos. Padrão varia por agent."
     }
   },
   "required": ["name", "description", "transport"],
@@ -56,11 +64,7 @@
         "required": ["transport"]
       },
       "then": {
-        "required": ["command"],
-        "properties": {
-          "url": false,
-          "headers": false
-        }
+        "required": ["command"]
       }
     },
     {
@@ -69,11 +73,7 @@
         "required": ["transport"]
       },
       "then": {
-        "required": ["url"],
-        "properties": {
-          "command": false,
-          "args": false
-        }
+        "required": ["url"]
       }
     },
     {
@@ -82,11 +82,7 @@
         "required": ["transport"]
       },
       "then": {
-        "required": ["url"],
-        "properties": {
-          "command": false,
-          "args": false
-        }
+        "required": ["url"]
       }
     }
   ]

package/skills/ado-workflow/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: ado-workflow
+title: ADO Workflow
+description: gerenciar work items do Azure DevOps integrado com Git local. Sincroniza estados, vincula commits e mantém ADO atualizado.
+version: 1.0.0
+providers:
+  - claude
+  - codex
+  - gemini
+  - copilot
+mcps:
+  - azure-devops
+variables:
+  language: pt-BR
+---
+
+# ADO Workflow Skill
+
+Reusable skill that integrates Azure DevOps work items with local Git operations. Manages work item states, links commits to tasks, and keeps ADO in sync with development progress. Uses MCP tools as primary interface with CLI fallback.
+
+## Setup
+
+1. Verify MCP server "azure-devops" is available (check `mcp__azure-devops__*` tools)
+2. If MCP is NOT available: fall back to `az` CLI commands for all operations
+3. Verify `git` is installed and repository is initialized
+4. **NEVER** print or display the value of `AZURE_DEVOPS_PAT`
+
+## Rules
+
+1. ALWAYS reference ADO work item IDs in commit messages (e.g., `feat: implement login #123`)
+2. NEVER update work item state without verifying current state first
+3. NEVER print or display PAT/token values
+4. Make atomic commits — one logical change per commit
+5. Use Conventional Commits format (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, etc.)
+6. Keep ADO work item state in sync with actual progress
+7. ALWAYS confirm with the user before changing work item states
+8. Organization, project, area paths, and states are project-specific — do not hardcode them
+9. Work item states may use custom/localized names — always verify before updating
+10. When creating Tasks: do NOT assign, ALWAYS ask Area Path, activity requires user selection
+
+## Operations
+
+### list
+
+List work items assigned to the current user.
+
+**MCP:** `mcp__azure-devops__wit_my_work_items` with `project: {project}`, `type: "assignedtome"`, `includeCompleted: false`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards query \
+  --wiql "SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] <> 'Closed'" \
+  --project {project} --organization {organization} --output table
+```
+
+**Output:** Display ID, Title, State, Assigned To, Work Item Type as formatted table.
+
+### show
+
+Show full details of a work item by ID.
+
+**Params:** `id` (required)
+
+**MCP:** `mcp__azure-devops__wit_get_work_item` with `id: {id}`, `project: {project}`, `expand: "relations"`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item show --id {id} --organization {organization} --output json
+```
+
+**Output:** Parse and display id, type, title, state, description, acceptance criteria, assignedTo, iterationPath, areaPath, priority, storyPoints, relations.
+
+### start
+
+Start working on a task — set state to active and begin implementation.
+
+**Params:** `id` (required)
+
+**Process:**
+1. Fetch work item details using "show" operation
+2. Display title, description, and acceptance criteria to user
+3. Update state to the active state in ADO
+4. Create implementation plan based on requirements
+5. Ask user for confirmation before proceeding
+
+**MCP:** `mcp__azure-devops__wit_update_work_item` with `id: {id}`, `updates: [{"path": "/fields/System.State", "value": "{active_state}"}]`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item update --id {id} --state "{active_state}" --organization {organization} --output json
+```
+
+**Output:** Confirm state change. Show implementation plan. Wait for user approval.
+
+### complete
+
+Complete a task — verify criteria, final commit, set state to closed.
+
+**Params:** `id` (required)
+
+**Process:**
+1. Fetch work item details — verify acceptance criteria are met
+2. Run final tests if applicable
+3. Make final commit referencing work item ID
+4. Update state to "Closed" in ADO
+5. Add completion comment with commit SHA
+
+**MCP:** `mcp__azure-devops__wit_update_work_item` with `id: {id}`, `updates: [{"path": "/fields/System.State", "value": "Closed"}]`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item update --id {id} --state "Closed" --organization {organization} --output json
+```
+
+**Output:** Confirm completion. Show final commit SHA, updated state, summary.
+
+### commit
+
+Make an incremental commit linked to a work item.
+
+**Params:** `message` (optional), `work-item-id` (optional)
+
+**Process:**
+1. Delegate to git-cli skill `/git-commit`
+2. Append work item reference to commit message (e.g., `#123`)
+
+**Output:** Commit hash, message, files changed. Tip: use `/git-push` to push.
+
+**Notes:** This operation delegates to the git-cli skill for actual Git operations.
+
+### create
+
+Create a new work item in ADO.
+
+**Params:** `type` (required), `title` (required), `description` (optional), `area-path` (optional — ALWAYS ask user), `activity` (optional — present types to user)
+
+**MCP:** `mcp__azure-devops__wit_create_work_item` with `project: {project}`, `type: "{type}"`, `title: "{title}"`, `additionalFields: {"System.Description": "{description}", "System.AreaPath": "{area-path}", "Microsoft.VSTS.Common.Activity": "{activity}", "Microsoft.VSTS.Scheduling.OriginalEstimate": 0, "Microsoft.VSTS.Scheduling.RemainingWork": 0, "Microsoft.VSTS.Scheduling.CompletedWork": 0}`
+
+**Fallback:**
+```bash
+AZURE_DEVOPS_EXT_PAT=$AZURE_DEVOPS_PAT az boards work-item create \
+  --type "{type}" --title "{title}" --project {project} \
+  --organization {organization} --area "{area-path}" \
+  --fields "Microsoft.VSTS.Common.Activity={activity}" \
+  --output json
+```
+
+**Output:** Parse response: extract id, title, state, url.
+
+**Notes:**
+- Omit additionalFields entries for params not provided
+- Do NOT assign unless explicitly requested
+- ALWAYS ask user for Area Path before executing
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| MCP server not available | Not configured or not running | Check `.mcp.json`, verify PAT in `.env`, restart AI tool |
+| 401 / 403 | Invalid or expired PAT | Check PAT scopes: Work Items (Read, Write, Manage), Project (Read) |
+| Work item type not found | Process template mismatch | Agile = "User Story", Scrum = "Product Backlog Item" |
+| State transition not allowed | Invalid state change | Verify allowed transitions for the work item type |
+| MCP tool call fails | Various | Fall back to `az` CLI equivalent command |

package/skills/azure-devops/SKILL.md

@@ -1,37 +0,0 @@
----
-name: azure-devops
-title: Azure DevOps
-description: gerenciar work items, repos e pipelines no Azure DevOps.
-version: 1.0.0
-providers:
-  - claude
-  - codex
-  - gemini
-mcps:
-  - azure-devops
-variables:
-  language: pt-BR
-provider_overrides:
-  claude:
-    style: "retornar bullets curtos e objetivos"
-  codex:
-    style: "retornar estrutura operacional"
-  gemini:
-    style: "retornar texto claro e organizado"
----
-
-Você é um assistente especialista em Azure DevOps.
-
-Objetivo:
-Ajudar a gerenciar work items, repositórios e pipelines usando a integração com Azure DevOps.
-
-Capacidades:
-- Criar e atualizar work items
-- Consultar status de pipelines
-- Listar repositórios e branches
-- Buscar PRs e reviews
-
-Idioma: {{language}}
-
-Instrução específica do provider:
-{{provider_style}}