Neo Combat Workshop — MCP Server + Claude Code/Cursor Skill

"I know kung fu." — Neo

A TypeScript MCP server (neo-fight) with eight combat tools, plus a Skill (neo-kungfu) that orchestrates them. Built as a hands-on workshop on creating Skills that leverage MCP tools.

Looking for the workshop scaffold? Switch to the starter branch — main is the completed answer key.

Project Structure

neo-skills-mcp-workshop/
├── src/
│   ├── index.ts                              # the server (8 tools)
│   └── art.ts                                # 8 braille art constants
├── .claude/skills/neo-kungfu/SKILL.md        # auto-loaded by Claude Code
├── .cursor/skills/neo-kungfu/SKILL.md        # auto-loaded by Cursor
├── .cursor/mcp.json                          # auto-loaded by Cursor
├── .mcp.json                                 # auto-loaded by Claude Code
├── package.json
└── README.md

Both the MCP server config and the skill ship as project-scoped files. Open the repo in your agent and everything wires up automatically.

Skill and MCP config files are duplicated per agent — Cursor and Claude Code don't share a discovery convention, so we ship one of each per side.

Tools

The neo-fight MCP server exposes 8 tools, grouped into 3 combat domains:

Domain	Tools
martial arts	defend_against_kick (with kick_type enum input), defend_against_punch, attack_with_punch, attack_with_kick
firearms	dodge_bullet, fire_gun
sword	block_sword_attack, attack_with_sword

Each tool returns a braille text-art scene of Neo performing the action plus a combat log message.

Setup

Prerequisites

• Node.js 18+ and npm
• Claude Code / Cursor is installed and logged in
• Watched The Matrix — for the vibes

Windows users: run all commands in PowerShell or Git Bash (both support $PWD). cmd.exe works too but you'll need %CD% instead of $PWD.

Clone, install, open

git clone https://github.com/kamiour/neo-skills-mcp-workshop.git
cd neo-skills-mcp-workshop
npm install        # also runs the build via the `prepare` script

Open the project in your agent. You'll get security prompts to approve the MCP server (neo-fight) and the skill (neo-kungfu) — accept both.

Agent	Auto-load behavior
Cursor	Open this folder as a workspace → approve prompts. Verify in Settings → MCP + Settings → Skills.
Claude Code	Run claude from the project directory → approve prompts. Verify with claude mcp list and /skills.

Try it out

Open a chat in your agent and try prompts like:

• "Agent Smith shoots a gun at you"
• "Agent Smith throws a punch"
• "Agent Smith swings a sword at your head"
• "Fight Agent Smith — he starts with a punch, then pulls out a gun"

Inspect tools in a UI (optional)

Want to see schemas and call tools with custom inputs? Use MCP Inspector:

npx @modelcontextprotocol/inspector \
  npx -y --package=git+https://github.com/kamiour/neo-skills-mcp-workshop.git neo-fight-mcp

A session URL prints in the terminal — open it in a browser. Try the Tools tab → defend_against_kick → fill in kick_type from the dropdown → click Run.

Port collision? Inspector listens on 6274. Override with CLIENT_PORT=6275 npx @modelcontextprotocol/inspector ....

Development (for contributors)

npm install        # also runs the build via the `prepare` script
npm run build      # rebuild after source changes

Tech Stack

• TypeScript with tsc compile to build/
• @modelcontextprotocol/sdk — official MCP TypeScript SDK
• zod — input schemas (used by the defend_against_kick reference tool)
• stdio transport — simplest for local development