MCP Server API
The MCP (Model Context Protocol) Server provides AI assistant integration for Bootspring, enabling AI tools like Claude to interact with your project through standardized tools and resources.
Overview#
Bootspring's MCP server exposes:
- Tools: Actions that can be performed (invoking agents, running quality checks, etc.)
- Resources: Read-only data about your project (context, todos, workflows)
Starting the MCP Server#
# Start MCP server (typically configured in claude_desktop_config.json)
bootspring mcpClaude Desktop Configuration#
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
1{
2 "mcpServers": {
3 "bootspring": {
4 "command": "npx",
5 "args": ["bootspring", "mcp"]
6 }
7 }
8}Available Tools#
bootspring_assist#
The primary "magic" tool for natural language assistance.
1{
2 "name": "bootspring_assist",
3 "description": "Natural language assistance with context detection",
4 "inputSchema": {
5 "properties": {
6 "request": { "type": "string", "description": "Natural language request" },
7 "context": { "type": "string", "description": "Additional context" }
8 },
9 "required": ["request"]
10 }
11}bootspring_context#
Manage project context and configuration.
1{
2 "name": "bootspring_context",
3 "inputSchema": {
4 "properties": {
5 "action": {
6 "enum": ["get", "refresh", "validate"],
7 "description": "Action to perform"
8 }
9 },
10 "required": ["action"]
11 }
12}bootspring_agent#
Work with specialized AI agents.
1{
2 "name": "bootspring_agent",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["list", "show", "invoke", "search"] },
6 "name": { "type": "string" },
7 "topic": { "type": "string" },
8 "query": { "type": "string" }
9 },
10 "required": ["action"]
11 }
12}bootspring_todo#
Manage project todos.
1{
2 "name": "bootspring_todo",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["list", "add", "done", "clear"] },
6 "text": { "type": "string" },
7 "id": { "type": "number" }
8 },
9 "required": ["action"]
10 }
11}bootspring_skill#
Search and retrieve code patterns.
1{
2 "name": "bootspring_skill",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["list", "show", "search", "sync"] },
6 "name": { "type": "string" },
7 "query": { "type": "string" },
8 "includeExternal": { "type": "boolean" },
9 "summary": { "type": "boolean" },
10 "sections": { "type": "string" },
11 "maxChars": { "type": "number" }
12 },
13 "required": ["action"]
14 }
15}bootspring_quality#
Run quality gates.
1{
2 "name": "bootspring_quality",
3 "inputSchema": {
4 "properties": {
5 "gate": { "enum": ["pre-commit", "pre-push", "pre-deploy"] }
6 },
7 "required": ["gate"]
8 }
9}bootspring_orchestrator#
Intelligent agent coordination and workflow management.
1{
2 "name": "bootspring_orchestrator",
3 "inputSchema": {
4 "properties": {
5 "action": {
6 "enum": ["analyze", "suggest", "recommend", "workflows", "workflow", "start", "next", "checkpoint", "status"]
7 },
8 "context": { "type": "string" },
9 "workflow": { "type": "string" },
10 "signal": { "type": "string" },
11 "limit": { "type": "number" }
12 },
13 "required": ["action"]
14 }
15}bootspring_loop#
Autonomous development loop management.
1{
2 "name": "bootspring_loop",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["status", "next", "complete", "skip"] },
6 "notes": { "type": "string" }
7 },
8 "required": ["action"]
9 }
10}bootspring_memory#
Git-based memory and learnings.
1{
2 "name": "bootspring_memory",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["extract", "search", "stats"] },
6 "query": { "type": "string" },
7 "files": { "type": "array", "items": { "type": "string" } },
8 "limit": { "type": "number" }
9 },
10 "required": ["action"]
11 }
12}bootspring_generate#
Generate or regenerate CLAUDE.md context.
1{
2 "name": "bootspring_generate",
3 "inputSchema": {
4 "properties": {
5 "force": { "type": "boolean" }
6 }
7 }
8}bootspring_dashboard#
Launch real-time dashboard.
1{
2 "name": "bootspring_dashboard",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["start", "status"] }
6 }
7 }
8}bootspring_capabilities#
Get available Bootspring capabilities.
1{
2 "name": "bootspring_capabilities",
3 "inputSchema": {
4 "properties": {}
5 }
6}bootspring_telemetry#
Manage telemetry settings.
1{
2 "name": "bootspring_telemetry",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["status", "enable", "disable"] }
6 },
7 "required": ["action"]
8 }
9}bootspring_plugin#
Manage plugins.
1{
2 "name": "bootspring_plugin",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["list", "enable", "disable"] },
6 "name": { "type": "string" }
7 },
8 "required": ["action"]
9 }
10}bootspring_seed#
Project seeding and scaffolding.
1{
2 "name": "bootspring_seed",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["status", "ingest", "scaffold", "presets"] },
6 "preset": { "type": "string" },
7 "dryRun": { "type": "boolean" }
8 },
9 "required": ["action"]
10 }
11}bootspring_mvp#
MVP import and analysis.
1{
2 "name": "bootspring_mvp",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["init", "analyze", "import"] },
6 "source": { "type": "string" }
7 },
8 "required": ["action"]
9 }
10}bootspring_prd#
PRD ingestion and todo creation.
1{
2 "name": "bootspring_prd",
3 "inputSchema": {
4 "properties": {
5 "action": { "enum": ["ingest", "status"] }
6 },
7 "required": ["action"]
8 }
9}Available Resources#
bootspring://context/project#
Current project context and configuration.
1// Returns JSON with project configuration
2{
3 "framework": "nextjs",
4 "database": "postgresql",
5 "hosting": "vercel",
6 // ...
7}bootspring://context/claude.md#
Generated AI context file content.
// Returns markdown content of CLAUDE.mdbootspring://context/todo.md#
Project todo list.
// Returns markdown todo listbootspring://agents/list#
Available specialized agents.
1// Returns JSON array of agents
2[
3 {
4 "id": "database-expert",
5 "name": "Database Expert",
6 "description": "...",
7 "expertise": ["SQL", "Prisma", ...]
8 },
9 // ...
10]bootspring://workflow/status#
Current workflow status.
1// Returns JSON with workflow state
2{
3 "phase": 4,
4 "phaseName": "Implementation",
5 "activeWorkflow": {
6 "name": "feature-development",
7 "step": 2,
8 "totalSteps": 4
9 },
10 "availableWorkflows": [...]
11}bootspring://skills/catalog#
Available skills catalog.
1// Returns JSON skills catalog
2{
3 "total": 45,
4 "skills": [
5 {
6 "id": "auth/clerk",
7 "name": "Clerk Authentication",
8 "description": "...",
9 "category": "auth"
10 },
11 // ...
12 ]
13}bootspring://memory/recent#
Recent decisions and learning insights.
1// Returns JSON with memory data
2{
3 "stats": { "total_decisions": 150, ... },
4 "recentDecisions": [...],
5 "topPatterns": [...]
6}JavaScript/Node.js API#
Module Import#
const { TOOLS, RESOURCES, toolHandlers, resourceHandlers } = require('bootspring/mcp/server');Tool Invocation#
invokeTool(toolName, args)#
Invoke a tool programmatically.
const { invokeTool } = require('bootspring/mcp/registry');
const result = await invokeTool('bootspring_agent', {
action: 'list'
});invokeToolSequence(toolCalls)#
Invoke multiple tools in sequence.
1const { invokeToolSequence } = require('bootspring/mcp/registry');
2
3const results = await invokeToolSequence([
4 { tool: 'bootspring_context', args: { action: 'get' } },
5 { tool: 'bootspring_quality', args: { gate: 'pre-commit' } }
6]);invokeToolParallel(toolCalls)#
Invoke multiple tools in parallel.
1const { invokeToolParallel } = require('bootspring/mcp/registry');
2
3const results = await invokeToolParallel([
4 { tool: 'bootspring_agent', args: { action: 'list' } },
5 { tool: 'bootspring_skill', args: { action: 'list' } }
6]);getAvailableTools()#
Get list of available tool names.
const { getAvailableTools } = require('bootspring/mcp/registry');
const tools = getAvailableTools();
// Returns: ['bootspring_assist', 'bootspring_context', ...]Telemetry#
trackTelemetry(event, payload)#
Track telemetry events from MCP tools.
1const { trackTelemetry } = require('bootspring/mcp/registry');
2
3trackTelemetry('tool_invoked', {
4 tool: 'bootspring_agent',
5 action: 'invoke'
6});Tool Response Format#
All tools return responses in the MCP content format:
Success Response#
1{
2 "content": [
3 {
4 "type": "text",
5 "text": "Response content or JSON string"
6 }
7 ]
8}Error Response#
1{
2 "content": [
3 {
4 "type": "text",
5 "text": "Error: Description of what went wrong"
6 }
7 ],
8 "isError": true
9}Creating Custom Tools#
Tool Definition Structure#
1function getToolDefinition() {
2 return {
3 name: 'bootspring_custom',
4 description: 'Description of what the tool does',
5 inputSchema: {
6 type: 'object',
7 properties: {
8 action: {
9 type: 'string',
10 enum: ['action1', 'action2'],
11 description: 'Action to perform'
12 },
13 // ... more properties
14 },
15 required: ['action']
16 }
17 };
18}Handler Implementation#
1function createHandler(dependencies) {
2 return async (args) => {
3 const { action } = args;
4
5 switch (action) {
6 case 'action1':
7 // Implement action
8 return {
9 content: [{
10 type: 'text',
11 text: JSON.stringify({ result: 'success' }, null, 2)
12 }]
13 };
14 default:
15 throw new Error(`Unknown action: ${action}`);
16 }
17 };
18}
19
20module.exports = {
21 getToolDefinition,
22 createHandler
23};Dependencies#
The MCP server requires:
npm install @modelcontextprotocol/sdk zodThese are included when installing Bootspring globally:
npm install -g @girardmedia/bootspringError Handling#
Missing Dependencies#
Bootspring MCP Server - Startup Failed
Missing dependencies:
- @modelcontextprotocol/sdk is not installed
To fix, run:
npm install @modelcontextprotocol/sdk zod
Unknown Tool#
1{
2 "content": [{
3 "type": "text",
4 "text": "Error: Unknown tool: invalid_tool"
5 }],
6 "isError": true
7}Tool Execution Error#
1{
2 "content": [{
3 "type": "text",
4 "text": "Error: Agent not found: invalid-agent"
5 }],
6 "isError": true
7}Best Practices#
- Use assist for natural language: The
bootspring_assisttool handles natural language and routes to appropriate tools - Check capabilities first: Use
bootspring_capabilitiesto see what's available - Combine tools: Use tool chaining for complex operations
- Handle errors gracefully: Always check for
isErrorin responses - Use resources for read-only data: Prefer resources over tools for fetching project state