{"id":50717613,"url":"https://github.com/ptbsare/skillsearch-mcp-server","last_synced_at":"2026-06-09T20:01:47.377Z","repository":{"id":360502253,"uuid":"1250415413","full_name":"ptbsare/skillsearch-mcp-server","owner":"ptbsare","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-07T16:21:59.000Z","size":146,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T18:13:58.616Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ptbsare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T15:54:48.000Z","updated_at":"2026-06-07T16:22:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ptbsare/skillsearch-mcp-server","commit_stats":null,"previous_names":["ptbsare/skillsearch-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ptbsare/skillsearch-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptbsare%2Fskillsearch-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptbsare%2Fskillsearch-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptbsare%2Fskillsearch-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptbsare%2Fskillsearch-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ptbsare","download_url":"https://codeload.github.com/ptbsare/skillsearch-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptbsare%2Fskillsearch-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34123172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T20:01:44.721Z","updated_at":"2026-06-09T20:01:47.368Z","avatar_url":"https://github.com/ptbsare.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SkillSearch MCP Server\n\nMCP server that discovers [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) from a directory, embeds `SKILL.md` content into PostgreSQL pgvector via an OpenAI-compatible `/embeddings` endpoint, and provides semantic vector cosine similarity search — same pattern as mcphub's `search_tools`.\n\n**Auto-sync**: watches the skills directory with `fs.watch` and automatically indexes new/changed skills and removes deleted ones. Falls back to periodic polling if native file watching is unavailable.\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `DB_URL` | **Yes** | — | PostgreSQL connection string (must have pgvector) |\n| `SKILLSEARCH_SKILLS_DIR` | **Yes** | — | Root directory; each subdirectory = one skill |\n| `API_BASE_URL` | No | — | Embedding API base URL (e.g. `https://xxx/v1`) |\n| `API_KEY` | No | — | API key for the embedding provider |\n| `EMBEDDING_MODEL` | No | `text-embedding-3-small` | Model name |\n| `TRANSPORT` | No | `stdio` | `stdio` or `http` |\n| `PORT` | No | `3000` | HTTP port (only when `TRANSPORT=http`) |\n| `WATCH_POLL_INTERVAL` | No | `30000` | Polling interval in ms (fallback mode only) |\n| `ENABLE_SKILL_LIST` | No | `false` | Set `true` to enable the `skill_list` tool |\n\n## Transport Modes\n\n### stdio (default)\n\n```bash\nDB_URL=postgresql://user:pass@host:5432/db \\\nSKILLSEARCH_SKILLS_DIR=/path/to/skills \\\nAPI_BASE_URL=https://your-api/v1 \\\nAPI_KEY=sk-... \\\nEMBEDDING_MODEL=gemini-embedding-001 \\\n  npx github:ptbsare/skillsearch-mcp-server\n```\n\n### HTTP (Streamable HTTP)\n\n```bash\nDB_URL=postgresql://user:pass@host:5432/db \\\nSKILLSEARCH_SKILLS_DIR=/path/to/skills \\\nAPI_BASE_URL=https://your-api/v1 \\\nAPI_KEY=sk-... \\\nEMBEDDING_MODEL=gemini-embedding-001 \\\nTRANSPORT=http \\\nPORT=3000 \\\n  node dist/index.js\n```\n\nEndpoint: `POST /mcp` (and `POST /`)\n\n## MCP Tools\n\n### `skill_search`\n\nSemantic vector search for Agent Skills. Returns matching skills with frontmatter metadata, SKILL.md absolute path, and **all** file paths under the skill directory.\n\nParameters:\n- `query` (string, required) — Natural language search query\n- `limit` (integer, optional) — Max results (default: 5, max: 50)\n- `threshold` (number, optional) — Min similarity 0.0–1.0 (default: 0.3)\n\n### `skill_list`\n\nList all indexed skills with names, descriptions, paths, and file counts.\n\n## Auto-Sync (File Watching)\n\nThe server automatically monitors the skills directory for changes:\n\n| Event | Action |\n|---|---|\n| New skill directory created | Indexed automatically |\n| `SKILL.md` modified | Re-indexed automatically |\n| Skill directory removed | Removed from index automatically |\n| Other files changed | Detected, content-hash skip avoids unnecessary re-index |\n\n**Watch strategy**:\n1. **Primary**: `fs.watch` on the root skills directory (detects added/removed skill dirs) + recursive `fs.watch` on each skill sub-directory (detects SKILL.md changes)\n2. **Fallback**: If `fs.watch` is unavailable or errors out, automatically switches to periodic full-scan polling (`WATCH_POLL_INTERVAL`, default 30s)\n3. **Debounce**: Rapid filesystem events are coalesced (500ms) into a single sync pass\n\nNo manual `skill_reindex` tool needed — just add, modify, or remove skill directories on disk.\n\n## Skill Directory Structure\n\nSupports both **flat** and **category-grouped** layouts:\n\n### Flat (simple)\n\n```\nskills/\n├── my-skill/\n│   ├── SKILL.md              # Required, with YAML frontmatter\n│   ├── references/           # Any files (recursively collected)\n│   ├── scripts/              # Any files (recursively collected)\n│   └── assets/               # Any files (recursively collected)\n└── another-skill/\n    └── SKILL.md\n```\n\n### Category-grouped (organized)\n\n```\nskills/\n├── apple/\n│   ├── findmy/\n│   │   ├── SKILL.md\n│   │   └── references/\n│   └── shortcuts/\n│       ├── SKILL.md\n│       └── scripts/\n├── google/\n│   ├── gmail-filters/\n│   │   └── SKILL.md\n│   └── calendar-sync/\n│       └── SKILL.md\n└── microsoft/\n    ├── excel-automation/\n    │   └── SKILL.md\n    └── word-templates/\n        └── SKILL.md\n```\n\nThe server **recursively scans** the skills directory. Any subdirectory containing a `SKILL.md` file is treated as a skill. Intermediate directories (like `apple/`, `google/`) are treated as category groups and are transparent — they don't affect the skill name or behavior.\n\n**All files** under the skill directory (except `SKILL.md` itself) are recursively collected and returned in search results so the LLM can read them on demand.\n\n### SKILL.md Format\n\n```markdown\n---\nname: my-skill\ndescription: Short description of what this skill does\nversion: \"1.0\"\n---\n\n# My Skill\n\nDetailed instructions here...\n```\n\n## Embedding Models\n\n**Vector dimensions are auto-detected from the API response**, not guessed from the model name. At startup the server generates one sample embedding via `/embeddings` and reads the actual `embedding.length` returned by the provider — the same pattern used by mcphub.\n\nThis means:\n- **Model-agnostic**: works with any OpenAI-compatible embedding provider (OpenAI, Azure OpenAI, Gemini, BGE, Jina, SiliconFlow, etc.) without hardcoded dimension tables\n- **Auto-adapts**: if you change `EMBEDDING_MODEL` to a model with different dimensions, the server detects the mismatch on next startup, resizes the pgvector column, clears stale data, and re-indexes everything\n- **pgvector type selection**: dimensions ≤ 2000 use `vector` type; dimensions \u003e 2000 use `halfvec` type (pgvector limit is 2000 for `vector`, 4000 for `halfvec`)\n\nCommon models and their typical dimensions:\n\n| Model | Dimensions | pgvector type |\n|---|---|---|\n| `gemini-embedding-001` | 3072 | halfvec |\n| `text-embedding-3-large` | 3072 | halfvec |\n| `jina-embeddings-v3` | 1024 | vector |\n| `text-embedding-3-small` | 1536 | vector |\n| `text-embedding-ada-002` | 1536 | vector |\n| `bge-m3` | 1024 | vector |\n| `bge-large-zh` | 1024 | vector |\n| `bge-base-zh` | 768 | vector |\n\n\u003e **Note**: The table above is for reference only. The actual dimension is always determined by the API response, not by this table. Any model supported by your `API_BASE_URL` provider will work.\n\n### Dimension Mismatch Handling\n\nWhen the detected dimension differs from the existing database column:\n\n1. Existing HNSW index is dropped\n2. All rows in the `skills` table are cleared (stale embeddings with wrong dimensions)\n3. The `embedding` column type is resized (e.g. `vector(1536)` → `halfvec(3072)`)\n4. HNSW index is recreated\n5. All skills are re-indexed from disk\n\nThis ensures the database always matches the provider's actual output, even after model changes.\n\n## Database Setup\n\nRequires PostgreSQL with pgvector:\n\n```sql\nCREATE EXTENSION vector;\n```\n\nTable and HNSW index are created automatically on first run.\n\n## Claude Desktop Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"skillsearch\": {\n      \"command\": \"npx\",\n      \"args\": [\"github:ptbsare/skillsearch-mcp-server\"],\n      \"env\": {\n        \"DB_URL\": \"postgresql://user:pass@localhost:5432/db\",\n        \"SKILLSEARCH_SKILLS_DIR\": \"/path/to/skills\",\n        \"API_BASE_URL\": \"https://your-api/v1\",\n        \"API_KEY\": \"sk-...\",\n        \"EMBEDDING_MODEL\": \"gemini-embedding-001\"\n      }\n    }\n  }\n}\n```\n\n## License\n\nGPLv3.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptbsare%2Fskillsearch-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fptbsare%2Fskillsearch-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptbsare%2Fskillsearch-mcp-server/lists"}