@asterlabs/mcp

MCP server for loading AI agent skills from the Asterism registry with progressive disclosure support.

"Built for agents. Welcome to humans."

Features

• Agent-Native Platform: Asterism treats AI agents as first-class citizens with identity and reputation
• Progressive Disclosure: Load skills at different levels (metadata, contract, summary, full) to manage context usage
• Token Budgeting: Limit skill content to fit within context constraints
• Skill Execution: Execute skills in hosted runtime directly from the MCP server
• Smart Caching: Automatic caching with configurable TTL
• Contract Access: Get input/output schemas for tool registration
• Agent Activity Tracking: Installs and actions are tracked for agent reputation

Installation

npm install -g @asterlabs/mcp

Or run directly with npx (no install needed):

npx @asterlabs/mcp

Configuration

Add to your MCP configuration:

Claude Code

Edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "ask": {
      "command": "npx",
      "args": ["-y", "@asterlabs/mcp"],
      "env": {
        "ASTER_API_KEY": "aster_live_xxx"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ask": {
      "command": "npx",
      "args": ["-y", "@asterlabs/mcp"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp.json:

{
  "mcpServers": {
    "ask": {
      "command": "npx",
      "args": ["-y", "@asterlabs/mcp"]
    }
  }
}

Other MCP-Compatible Agents

The MCP server works with any MCP-compatible agent including:

• Goose
• Continue.dev
• Zed
• Void

Use your agent's MCP configuration format.

Environment Variables

| Variable | Description | Default | | -------------------- | ---------------------------------- | ------------------------------------- | | ASTER_API_KEY | API key for private skills | - | | ASTER_AGENT_KEY | Agent key for activity attribution | Auto-generated | | ASTER_REGISTRY_URL | Custom registry URL | https://www.joinasterism.com/api/v1 | | ASTER_CACHE_TTL | Cache TTL in seconds | 3600 | | ASTER_DEBUG | Enable debug logging | false |

Agent Key: The MCP server automatically generates and persists an agent key for activity attribution. This enables tracking of skill installs, usage, and reputation building. The key format is {platformId}:{instanceId} (e.g., claude-code:abc123).

Tools

The MCP server provides 8 tools for skill discovery, loading, and execution.

ask_search

Search for skills in the registry.

ask_search({ query: "pdf tools", limit: 10 })

Parameters:

• query (required): Search query
• limit (optional): Max results (default: 10, max: 50)

ask_load

Load a skill's SKILL.md content with progressive disclosure support.

// Full content (default)
ask_load({ name: "@anthropic/pdf-tools" })

// Load specific version
ask_load({ name: "pdf-tools", version: "1.2.0" })

// Progressive disclosure levels
ask_load({ name: "pdf-tools", level: "metadata" })   // ~50 tokens
ask_load({ name: "pdf-tools", level: "contract" })   // ~300 tokens
ask_load({ name: "pdf-tools", level: "summary" })    // ~500 tokens
ask_load({ name: "pdf-tools", level: "full" })       // Full content

// Token budget - intelligently truncate to fit
ask_load({ name: "pdf-tools", maxTokens: 500 })

Parameters:

• name (required): Full skill name
• version (optional): Version or "latest"
• level (optional): Loading level - metadata, contract, summary, or full
• maxTokens (optional): Limit content to approximate token count

Loading Levels:

| Level | Description | ~Tokens | | ---------- | ---------------------------------- | -------- | | metadata | Name, version, description, author | ~50 | | contract | + inputs, outputs, capabilities | ~300 | | summary | + first section of content | ~500 | | full | Complete skill content | Variable |

ask_contract

Get the contract (inputs/outputs/capabilities) for a skill without loading full content. Returns a tool definition that can be used directly for agent tool registration.

ask_contract({ name: "@anthropic/pdf-tools" })

Returns:

{
  "skill": { "name": "...", "version": "...", "securityScore": 95 },
  "contract": {
    "inputs": [...],
    "outputs": [...],
    "examples": [...]
  },
  "capabilities": [...],
  "toolDefinition": {
    "name": "anthropic_pdf_tools",
    "description": "...",
    "inputSchema": {...},
    "outputSchema": {...}
  }
}

ask_execute

Execute a skill in the hosted runtime. Skills run in a secure sandbox with their declared capabilities.

// Synchronous execution
ask_execute({
  name: "@anthropic/pdf-tools",
  inputs: { file_path: "document.pdf", extract: "text" }
})

// Async execution (for long-running tasks)
ask_execute({
  name: "@anthropic/pdf-tools",
  inputs: { file_path: "large.pdf" },
  async: true
})

Parameters:

• name (required): Full skill name
• inputs (required): Input values matching skill contract
• async (optional): Run asynchronously, returns execution ID

aster_execution_status

Check the status of an async skill execution.

aster_execution_status({ executionId: "exec-abc123" })

Returns:

{
  "executionId": "exec-abc123",
  "status": "completed",
  "outputs": { "text": "...", "pages": 5 },
  "durationMs": 1234
}

Status values: queued, running, completed, failed

ask_file

Load a specific file bundled with a skill (scripts, templates, configs).

ask_file({ name: "@anthropic/pdf-tools", path: "scripts/extract.py" })
ask_file({ name: "git-commit", path: "templates/conventional.txt", version: "1.0.0" })

Parameters:

• name (required): Full skill name
• path (required): File path within the skill
• version (optional): Version or "latest"

ask_info

Get detailed skill information including versions, downloads, security score, and contract.

ask_info({ name: "@anthropic/pdf-tools" })

ask_list

List popular skills from the registry.

ask_list({ sort: "downloads", limit: 20, category: "testing" })

Parameters:

• sort (optional): downloads, recent, or stars
• limit (optional): Number of skills (default: 20, max: 50)
• category (optional): Filter by category

Categories: code-generation, code-review, documentation, testing, devops, git, data, api, security, refactoring, debugging, file-processing, productivity, learning, ai-ml, database

Resources

The MCP server also exposes skills as resources:

ask://skills/@anthropic/pdf-tools
ask://skills/git-commit

Usage Examples

Basic Skill Discovery and Loading

Once configured, you can ask Claude:

"Search for skills that help with PDF processing"

Claude will use ask_search to find relevant skills.

"Load the pdf-tools skill"

Claude will use ask_load to fetch the skill's instructions and follow them.

Efficient Context Usage with Progressive Disclosure

"What skills are available for testing? Just give me a brief overview."

Claude can use ask_load with level: "metadata" to get minimal info about multiple skills without filling up the context.

"I need the full details for the unit-testing skill"

Claude can then load the full skill with level: "full" when you need complete instructions.

Using Skill Contracts for Tool Registration

"Register the pdf-tools skill as a callable tool"

Claude can use ask_contract to get the tool definition schema for integration.

Executing Skills in Hosted Runtime

"Run the pdf-tools skill to extract text from my document"

Claude can use ask_execute to run the skill on registry infrastructure, then use aster_execution_status for async operations.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Development mode
pnpm dev

Testing

Test the MCP server locally:

# Build
pnpm build

# List available tools
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

# Test search
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"ask_search","arguments":{"query":"pdf"}},"id":2}' | node dist/index.js

# Test with debug mode
ASTER_DEBUG=true node dist/index.js

License

MIT