NickRimmer/md-skills-mcp

Markdown Skills MCP Server

Put your tool files in a folder (subfolders allowed) and expose them as MCP tools.

• Markdown: Each .tool.md file becomes a tool whose instructions are templated with {{placeholders}}.
• PowerShell: Each .tool.ps1 file has commented frontmatter metadata plus a script body.
• TypeScript: Each .tool.ts file exports a description, parameters, and runTool function.

All files must contain .tool. in the end of their filename before the extension, otherwise they are ignored.

Using the MCP server

Example .vscode/mcp.json entries you can use to launch the server from an MCP-capable client.

Add MCP server

{
  "servers": {
    "mdSkills": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "md-skills-mcp",
        "--folder",
        ".github/my-tools" // <-- your tools folder here, not necessary in ".github" folder
      ]
    }
  },
  "inputs": []
}

Notes:

The server only reads the folder at startup (no hot-reload). Invalid or malformed Markdown tools are skipped with a console warning.

Supported tools

Tools can be defined via Markdown, TypeScript, or PowerShell files.

Markdown format

• Filename: [A-Za-z0-9_]+.tool.md (others and hidden files are ignored).
• Body: instruction template. Use {{param_name}} placeholders (names must be [A-Za-z0-9_]+). Optional params missing at call time render as empty strings.

---
description: "Greets a user"
name: "Name to greet"
---
Hello, {{name}}

PowerShell format

• Filename: [A-Za-z0-9_]+.tool.ps1.
• pwsh must be available on the PATH; scripts run with -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass.

# ---
# description: Greets a user
# name: Name to greet
# ---
param(
  [string]$name,
)

Write-Output "Hello, $name"

TypeScript format

• Filename: [A-Za-z0-9_]+.tool.ts (others and hidden files are ignored).
• Exports from example below are required.
• Dependencies: TypeScript tools can import any packages installed alongside the tool file. The server transpiles .ts files at load time; no prebuild required.

export const description = "Greets a user";

export const parameters = {
  name: "Name to greet",
};

export async function runTool(props: Record<string, unknown>): Promise<unknown> {
  const name = String(props.name || 'stranger');
  return `Hello, ${name}`;
}