MCP Server
The airs-mcp is an optional MCP (Model Context Protocol) server that extends AI assistants with capabilities that pure prompting can't provide.
When Do You Need It?
You don't need the MCP server if:
- You just want to read and follow skills (use the docs site or raw files)
- You're contributing skills (use the CLI validator)
- Your AI assistant can read the skill files directly
You need the MCP server if:
- You want AI-assisted skill discovery and filtering
- You need semantic search across skills
- You want structured tool access beyond text-based prompting
What It Solves
Skills are documentation — they tell you how to do something. But some research tasks require:
- Structured queries: Filter skills by tags, search semantically
- Semantic search: Find skills by meaning, not just keywords
- Programmatic access: Machine-readable skill data for AI clients
The MCP server provides these as callable tools that AI clients can invoke.
Runtime Model
Default: Local Skills Directory
npm install
npm run mcp -- --skills-dir ./skills
The server reads skills.semantic.json from docs/public/ (generated by the sync script). It will also try to auto-discover this file by walking up parent directories, so running from the repo root is usually enough.
Alternative: Pre-built Catalog
npm install
npm run mcp -- --catalog ./catalog.json
Use a pre-generated JSON catalog for faster startup (useful in production).
Implemented Tools
| Tool | Description |
|---|---|
skills.list | List skills with optional filtering (category, tags) |
skills.get | Get full skill content by ID |
skills.semantic_search | Semantic search with keyword fallback |
skills.semantic_search
Search skills by meaning using natural language queries:
{
"method": "skills.semantic_search",
"params": {
"query": "how to analyze text patterns",
"top_k": 5
}
}
Returns:
{
"results": [
{ "id": "analysis.textual-analysis-basic", "score": 8.0, "title": "...", "summary": "..." }
],
"method": "keyword_fallback",
"provider": "none"
}
Fallback Behavior:
When no embedding provider is configured, the search uses keyword-based ranking:
- Title matches: 3.0 points
- Summary matches: 2.0 points
- Tag matches: 1.5 points
- Content matches: 1.0 points
Environment Configuration
| Variable | Values | Description |
|---|---|---|
AIRS_EMBED_PROVIDER | none, cloudflare | Embedding provider for semantic search |
# Use Cloudflare AI for semantic ranking
export AIRS_EMBED_PROVIDER=cloudflare
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_API_TOKEN=...
npm run mcp -- --skills-dir ./skills
Client Configuration
Claude Code / Claude Desktop
Add to your MCP settings (~/.claude/settings.json or similar):
{
"mcpServers": {
"airs": {
"command": "/path/to/ai-research-skills/node_modules/.bin/tsx",
"args": ["/path/to/ai-research-skills/mcp/airs-mcp.ts", "--skills-dir", "/path/to/ai-research-skills/skills"]
}
}
}
Other MCP Clients
Any MCP-compatible client can connect using stdio transport:
{
"command": "tsx",
"args": ["mcp/airs-mcp.ts", "--skills-dir", "./skills"],
"transport": "stdio"
}
Status
Working - Core tools implemented with keyword fallback; Cloudflare semantic ranking is supported.
Run with --health (or health) to verify it's working:
npm run mcp:health
# {"status":"ok","message":"AI Research Skills MCP server","skills_loaded":2,"embed_provider":"none"}