Aller au contenu principal

MCP Server Quick Start Guide

What is MCP?​

The Model Context Protocol (MCP) is an open standard that allows Large Language Models (LLMs) like GitHub Copilot to interact with external systems and APIs in a standardized way. This integration exposes your Baldr API capabilities to LLMs directly in VS Code.

Quick Start​

1. Build the Project​

npm run build

2. Configure VS Code MCP Server​

Your MCP server is already configured in .vscode/mcp.json:

{
  "servers": {
    "BaldrApi": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/home/romain/Dev/projects/BaldrTs/dist/mcp-server.js"
      ],
      "env": {
        "NODE_ENV": "development"
      }
    }
  },
  "inputs": []
}

✅ This configuration is ready to use! The MCP server will automatically start when you interact with Copilot.

3. Using with GitHub Copilot in VS Code​

  1. Open Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I)
  2. Use the @ symbol to access MCP tools: @BaldrApi
  3. Ask questions about your API:

Example prompts:

"@BaldrApi check the health of the Baldr API"
"@BaldrApi list all available modules"
"@BaldrApi what tools are available?"

4. Test the Connection (Optional)​

You can manually test the MCP server:

npm run mcp:test

HTTP Testing Interface​

While the MCP server primarily uses stdio transport, you can also test it via HTTP:

# Check server status
curl http://localhost:3000/api/mcp/status

# Get server info
curl http://localhost:3000/api/mcp/info

# List tools (requires authentication)
curl http://localhost:3000/api/mcp/tools \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Available Tools​

Out of the box, these tools are available:

  1. get_api_health - Check API health status
  2. list_modules - List all available modules
  3. query_collection - Query MongoDB collections
  4. get_api_stats - Get API usage statistics

Customizing Tools​

Adding a New Tool​

Edit src/configs/mcp.config.ts and add:

mcpService.registerTool(
  "my_tool_name",
  "Description of what this tool does",
  {
    type: "object",
    properties: {
      parameter1: {
        type: "string",
        description: "What this parameter does",
      },
    },
    required: ["parameter1"],
  },
  async (args) => {
    // Your implementation here
    return { result: "success" };
  }
);

Using Real API Operations​

See src/configs/mcp.advanced.config.ts for examples of integrating with:

  • User management
  • Product queries
  • Order processing
  • Analytics
  • Module management

To enable advanced tools, uncomment the relevant sections and import into mcp-server.ts.

Troubleshooting​

MCP Server Not Available in VS Code​

  • Verify .vscode/mcp.json exists and is properly formatted
  • Check that npm run build completed successfully
  • Ensure dist/mcp-server.js exists
  • Reload VS Code window (Ctrl+Shift+P → "Developer: Reload Window")

Connection Errors​

  • Check that environment variables are set in your .env file
  • Verify database connection is working
  • Check VS Code Developer Tools for MCP-related errors (Help → Toggle Developer Tools)
  • Make sure MongoDB is running

Tools Not Executing​

  • Check that the tool is registered in mcp.config.ts
  • Verify your implementation doesn't have errors
  • Look for error messages in the server logs

Build Fails​

# Clean build
npm run build

# Check for TypeScript errors
npx tsc --noEmit

Environment Variables​

Make sure your .env file includes:

NODE_ENV=development
PORT=3000
MONGODB_URI=mongodb://localhost:27017/your_database
# ... other required variables

Security Notes​

  1. Authentication: HTTP endpoints can use your existing auth middleware
  2. Stdio Transport: The MCP server uses stdio (stdin/stdout), which is secure for local/trusted environments
  3. Tool Permissions: Consider which operations should be exposed via MCP
  4. Logging: All operations are logged via Pino

Next Steps​

  1. ✅ Build the project with npm run build
  2. ✅ Verify .vscode/mcp.json configuration
  3. ✅ Open Copilot Chat and use @BaldrApi
  4. ✅ Test tools with Copilot
  5. 📝 Customize tools for your specific needs
  6. 📝 Implement real API operations in tools
  7. 📝 Add authentication/authorization as needed

Resources​

Example Conversations with GitHub Copilot​

Once configured, you can have conversations in VS Code like:

You: "@BaldrApi What's the status of the Baldr API?"

Copilot: Uses get_api_health tool and reports the status

You: "@BaldrApi Can you list all active modules?"

Copilot: Uses list_modules tool with includeInactive=false

You: "@BaldrApi Query the users collection"

Copilot: Uses query_collection tool with appropriate parameters

Enjoy using your API with GitHub Copilot in VS Code! 🎉