INTEGRATION.mdā¢7.17 kB
# š MCP Server Integration Guide
This guide explains how to integrate the NTV Scaffolding MCP Server with various AI clients and development tools.
## Table of Contents
1. [Cursor Editor](#cursor-editor)
2. [VS Code with Extensions](#vs-code-with-extensions)
3. [Claude API](#claude-api)
4. [Command Line](#command-line)
---
## Cursor Editor
Cursor has built-in MCP support. Here's how to configure it:
### Step 1: Start the MCP Server
```bash
cd C:\Users\Admin\Documents\repos\component-mcp
npm install
npm run build
npm start
```
### Step 2: Configure Cursor
1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Search for "MCP" or "Model Context Protocol"
3. Add a new server configuration:
```json
{
"name": "ntv-scaffolding",
"command": "node",
"args": ["C:\\Users\\Admin\\Documents\\repos\\component-mcp\\dist\\index.js"]
}
```
### Step 3: Test the Integration
1. Open the command palette (Cmd/Ctrl + K)
2. Type `@ntv` and you should see available NTV components
3. Ask questions like:
- "List all NTV components"
- "Show me the Button component documentation"
- "Generate a primary button template"
---
## VS Code with Extensions
### Option 1: Using MCP Client Extension
1. Install the MCP Client extension from VS Code marketplace
2. Add this to your `.vscode/settings.json`:
```json
{
"mcp.servers": {
"ntv-scaffolding": {
"command": "node",
"args": ["C:\\Users\\Admin\\Documents\\repos\\component-mcp\\dist\\index.js"],
"env": {}
}
}
}
```
### Option 2: Using Cody (Sourcegraph)
1. Install Cody extension
2. In Cody settings, add your MCP server configuration
3. Use Cody chat to interact with NTV components
---
## Claude API
To use the MCP Server with Claude API:
### Step 1: Set Up Claude SDK
```bash
npm install @anthropic-ai/sdk
```
### Step 2: Create a Client Script
Create `claude-client.js`:
```javascript
const Anthropic = require("@anthropic-ai/sdk");
const { spawn } = require("child_process");
const client = new Anthropic.default();
// Start MCP Server
const server = spawn("node", [
"C:\\Users\\Admin\\Documents\\repos\\component-mcp\\dist\\index.js",
]);
async function askAboutComponents(question) {
const message = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
messages: [
{
role: "user",
content: question,
},
],
});
console.log(message.content[0].text);
server.kill();
}
askAboutComponents(
"List all available NTV Scaffolding components and their categories"
);
```
### Step 3: Run
```bash
node claude-client.js
```
---
## Command Line
### Using the Server Directly
```bash
# List all components
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | npm start
# Get component documentation
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_ntv_component_doc", "arguments": {"component": "Button"}}, "id": 2}' | npm start
```
### Creating a Shell Script
Create `interact.sh`:
```bash
#!/bin/bash
# Start server in background
npm start &
SERVER_PID=$!
# Give server time to start
sleep 2
# Define functions for common tasks
function list_components() {
echo "Listing NTV components..."
# Call the MCP server
}
function get_docs() {
echo "Getting documentation for $1..."
# Call the MCP server
}
# Keep server running
wait $SERVER_PID
```
---
## Configuration Files
### .env Variables (Optional)
Create `.env` file:
```
MCP_PORT=3000
DEBUG=false
LOG_LEVEL=info
```
### Package.json Scripts
Add these scripts to `package.json` for easy management:
```json
{
"scripts": {
"start:server": "node dist/index.js",
"start:dev": "ts-node src/index.ts",
"build": "tsc",
"watch": "tsc --watch",
"test": "jest",
"lint": "eslint src --ext .ts"
}
}
```
---
## Docker Setup
Create `Dockerfile`:
```dockerfile
FROM node:20-alpine
WORKDIR /app
# Copy package files
COPY package*.json ./
# Install dependencies
RUN npm ci --only=production
# Copy compiled code
COPY dist ./dist
# Expose MCP protocol
EXPOSE 3000
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD node -e "console.log('OK')"
# Start server
CMD ["npm", "start"]
```
Build and run:
```bash
docker build -t ntv-mcp-server .
docker run -p 3000:3000 ntv-mcp-server
```
---
## Environment-Specific Configurations
### Development
```json
{
"environment": "development",
"debug": true,
"port": 3000,
"logLevel": "debug"
}
```
### Production
```json
{
"environment": "production",
"debug": false,
"port": 8080,
"logLevel": "info"
}
```
---
## Troubleshooting
### Server Won't Connect
1. **Check Node version**
```bash
node --version # Should be 18+
```
2. **Verify build**
```bash
npm run build
npm start
```
3. **Check logs**
```bash
npm start 2>&1 | grep -i error
```
### Tools Not Available
1. **Restart server** - MCP clients cache tool definitions
2. **Check tool exports** - Verify tools are in `src/tools/index.ts`
3. **Rebuild** - Run `npm run build` after changes
### Connection Timeout
- Ensure server is running before client connects
- Check firewall settings if using network transport
- Increase timeout in client configuration
---
## Best Practices
1. **Always rebuild after changes**
```bash
npm run build
```
2. **Use config pattern** for cleaner component usage
```json
{
"useConfigPattern": true
}
```
3. **Test tools individually** before using in AI clients
4. **Monitor server logs** for issues
5. **Keep component database updated** with new components
---
## Advanced Usage
### Custom Tool Development
Add new tools by:
1. Creating a file in `src/tools/`
2. Implementing `MCPTool` interface
3. Exporting from `src/tools/index.ts`
Example:
```typescript
export const myCustomTool: MCPTool = {
name: "my_custom_tool",
description: "Custom tool description",
inputSchema: { /* JSON schema */ },
execute: async (args) => {
// Implementation
return result;
},
};
```
### Extending Component Database
Add new components by editing `src/data/components.ts`:
```typescript
{
name: "MyComponent",
selector: "lib-my-component",
category: "ui",
description: "My custom component",
props: [
{
name: "prop1",
type: "string",
description: "A property",
},
],
}
```
---
## Performance Optimization
### Caching
The MCP server caches component database. To refresh:
```bash
npm run build
npm start
```
### Resource Management
- Use `list_ntv_components` with filters instead of getting all
- Cache documentation responses in your client
- Batch multiple requests when possible
---
## Security Considerations
1. **Input Validation** - All inputs are validated
2. **No File System Access** - Component data is read-only
3. **Sandboxed Execution** - Each tool runs in isolation
---
## Support
For issues or questions:
1. Check the README.md
2. Review tool schemas for parameter requirements
3. Check component database for available components
4. See troubleshooting section above
---
**Happy integrating! š**