npm package: @mcborov01/skill-manager-mcp
Description: MCP server + UI to create, edit, and manage AI agent skills
Latest version: 1.0.0

# Skill Manager MCP

Skill Manager MCP is a combined web UI and MCP server for managing AI agent skills. It gives you a browser-based interface for creating, editing, deleting, searching, and importing skills, and it exposes MCP tools so desktop clients and agent frameworks can discover and load those skills programmatically.

## Quick Start

Run the package directly with `npx`:

```bash
npx @mcborov01/skill-manager-mcp
```

Then open:

```text
http://localhost:3000
```

The web UI starts on port `3000` by default.

## Install Globally

```bash
npm install -g @mcborov01/skill-manager-mcp
skill-manager-mcp
```

This starts the web UI so you can manage your skill library locally.

## What You Get

- A local web UI for managing skills in SQLite
- Search by keyword or semantic similarity
- Optional OpenAI embedding support
- Markdown skill import for bulk loading skills
- MCP tools for listing and loading skills from compatible clients

## MCP Server

The project also ships an MCP server so tools such as Claude Desktop, Cursor, or custom agent runtimes can access the same skill library.

### Stdio Transport

Use stdio when your MCP client launches the server as a subprocess.

Direct commands:

```bash
node src/mcp.js
```

You can also wire it into MCP client configuration.

`mcp.json` or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "skill-manager": {
      "command": "npx",
      "args": ["-y", "--package", "@mcborov01/skill-manager-mcp", "skill-manager-mcp-server"]
    }
  }
}
```

If the package is installed locally instead:

```json
{
  "mcpServers": {
    "skill-manager": {
      "command": "skill-manager-mcp-server"
    }
  }
}
```

### HTTP Transport

To expose the MCP server over HTTP:

```bash
MCP_HTTP_PORT=3001 node src/mcp.js
```

Then point your MCP client at:

```text
http://localhost:3001/mcp
```

## Embedding Setup

Embedding-based semantic search is optional.

Set `OPENAI_API_KEY` to enable embeddings. If it is not set, the application falls back to keyword search automatically.

Example:

```bash
export OPENAI_API_KEY=your_api_key_here
```

You can also override the embedding model:

```bash
export OPENAI_EMBEDDING_MODEL=text-embedding-3-small
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3000` | Web UI port |
| `HOST` | `127.0.0.1` | Web UI host |
| `MCP_HTTP_PORT` | - | Enable HTTP transport on this port |
| `OPENAI_API_KEY` | - | Enable embedding-based search |
| `OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model |
| `SKILL_DB_PATH` | `./skills.db` | SQLite database path |

## MCP Tools

The MCP server exposes two tools.

### `list_skills`

Searches the skill library and returns matching skills with metadata and relevance scores.

Parameters:

| Parameter | Type | Required | Description |
|---|---|---|---|
| `keywords` | `string` | No | Keywords or natural-language search text |
| `query` | `string` | No | Alias for natural-language search text |
| `mode` | `auto \| keyword \| embedding` | No | Search strategy |
| `limit` | `number` | No | Maximum number of results, from `1` to `100` |

Returns fields including:

- `id`
- `title`
- `description`
- `purpose`
- `keywords`
- `score`
- `matchMode`

### `load_skill`

Loads a single skill by its numeric ID.

Parameters:

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `number` | Yes | Skill ID from `list_skills` |

Returns the full skill record, including the stored markdown content and metadata.

## Markdown Import

The web UI includes a markdown import form so you can bulk-create skills from pasted text.

Supported formats include:

- Frontmatter-based skill documents
- `[Skill: Title]` blocks
- Markdown documents with `# Heading` titles

Example frontmatter format:

```md
---
name: PostgreSQL Expert
description: Guidance for PostgreSQL schema design and operations
purpose: Help agents work with production PostgreSQL safely
keywords: postgres, sql, database, indexing
---
# PostgreSQL Expert

Use this skill when working with PostgreSQL migrations, indexing strategy, query review, and incident response.
```

You can paste one or multiple skills into the import form. When embeddings are enabled, imported skills also receive generated embeddings for semantic search.

## Local Development

If you are working from the repository directly:

```bash
npm install
node src/web.js
```

For stdio MCP:

```bash
node src/mcp.js
```

For the web UI, open:

```text
http://localhost:3000
```

## Storage

Skills are stored in a local SQLite database. By default the database file is:

```text
./skills.db
```

Override it with `SKILL_DB_PATH` if you want to store data elsewhere.