Deft Suite

v1.0.0-beta.5 — Changelog

An MCP server for discovering, validating, installing, and managing reusable agent skills.

• Unified search across local skills, team catalogs, and GitHub (opt-in)
• Secure install/save with validation and security scanning
• Trust-aware skill lifecycle with lock tracking
• Frecency ranking blending keyword relevance with local usage patterns
• Offline-first — graceful degradation when remotes are unavailable
• Project-aware config overlays with multi-path discovery

Prerequisites

• Node.js >=22.0.0
• A package manager: bun (recommended), pnpm, or npm
• Build toolchain for native addons (better-sqlite3)
• Optional: mise for pinned runtime versions

Installation

From GitHub (no npm publish required)

npm install -g github:kvithayathil/deft-suite

Or pin a specific tag:

npm install -g github:kvithayathil/deft-suite#v1.0.0-beta.5

From npm (once published)

npm install -g deft-mcp

From source (development)

git clone https://github.com/kvithayathil/deft-suite.git
cd deft-suite
mise install          # install pinned runtimes (node, bun, deno, pnpm)
bun install           # or: npm install
bun run build         # or: npm run build
npm link

This makes the deft CLI available globally via symlink.

Run

Start the MCP server over stdio:

node dist/index.js          # Node.js
bun dist/index.js           # Bun
deno task run                # Deno

Or use the CLI:

deft --help                 # if installed globally
node dist/cli.js --help     # Node.js
bun dist/cli.js --help      # Bun
deno task cli -- --help      # Deno

MCP Client Setup

Most clients use the same mcpServers JSON — what differs is the config file location. See the full Client Setup Guide for step-by-step instructions per client.

One-click install

All clients

Client	Config Location	Format Notes
	~/Library/Application Support/Claude/claude_desktop_config.json	Standard mcpServers
	claude mcp add or ~/.claude.json	CLI command preferred
	~/.codeium/windsurf/mcp_config.json	Standard mcpServers
	.cursor/mcp.json or global	One-click install · guide
	.vscode/mcp.json	One-click install · guide
	Settings UI	One-click install · guide
	~/.config/opencode/config.json or opencode.jsonc	Uses mcp key — different format · guide
	~/.zed/settings.json	Uses context_servers — different format
	Settings UI or .mcp.json	Uses servers key + type field
	CLI flag --mcp-config	Standard mcpServers in file

Tip: VS Code, VS Code Insiders, Cursor, and Visual Studio badges are one-click install links — they open the client and configure the MCP server automatically. Other badges link to the setup guide.

{
  "mcpServers": {
    "deft-mcp": {
      "command": "npx",
      "args": ["-y", "github:kvithayathil/deft-suite", "deft-mcp"]
    }
  }
}

{
  "mcpServers": {
    "deft-mcp": {
      "command": "npx",
      "args": ["-y", "github:kvithayathil/deft-suite#v1.0.0-beta.5", "deft-mcp"]
    }
  }
}

{
  "mcpServers": {
    "deft-mcp": {
      "command": "deft-mcp"
    }
  }
}

Quick Start

1. Start the server
2. get_status — confirm health
3. search_skills — find skills across all sources
4. install_skill — install with validation + scanning
5. get_skill — retrieve full content with trust indicator
6. save_skill — create your own

Tools

CLI

deft search "python" --refresh
deft stats
deft usage export --format json
deft usage reset --all

Documentation

Contributing

Contributions welcome. Add tests for behavioral changes and keep docs aligned with implementation.

Development Setup

git clone https://github.com/kvithayathil/deft-suite.git
cd deft-suite
mise install       # install pinned runtimes (optional but recommended)
bun install        # or: npm install — also configures git hooks
bun run build      # or: npm run build

Recommended: Install gitleaks for pre-commit secret scanning:

brew install gitleaks   # macOS

Quality Checks

All checks run automatically via pre-commit hook and CI:

Shortcuts via mise:

mise run check    # fmt:check + typecheck + lint
mise run ci       # full CI pipeline locally

See SECURITY.md for the full security tooling overview.

Third-Party Notices

This project uses the following direct runtime dependencies:

Full license texts are in THIRD-PARTY-NOTICES.md.

License

GPL-3.0 — All derivative works must remain open source. See the GNU General Public License v3.0 for details.