Role-Specific Context MCP Server

by Chris-June
Verified
# Role-Context MCP: API Documentation ## Overview This document provides detailed information about the HTTP API endpoints exposed by the Role-Context MCP server. The server runs on port 3000 by default. ## Base URL ``` http://localhost:3000 ``` ## Authentication Currently, the API does not require authentication. In a production environment, you should implement proper authentication and authorization. ## Endpoints ### Health Check #### GET /health Check if the server is running. **Response:** ```json { "status": "ok", "version": "1.0.0" } ``` ### Role Management #### GET /roles Get all available roles. **Response:** ```json { "roles": [ { "id": "marketing-expert", "name": "Marketing Expert", "description": "Specializes in marketing strategy, branding, and campaign development", "instructions": "Provide actionable marketing advice and strategies", "domains": ["marketing", "advertising", "branding"], "tone": "professional", "systemPrompt": "You are a marketing expert with 15+ years of experience...", "isDefault": true }, // More roles... ] } ``` #### GET /roles/:roleId Get a specific role by ID. **Parameters:** - `roleId` (path parameter): The ID of the role to retrieve **Response:** ```json { "role": { "id": "marketing-expert", "name": "Marketing Expert", "description": "Specializes in marketing strategy, branding, and campaign development", "instructions": "Provide actionable marketing advice and strategies", "domains": ["marketing", "advertising", "branding"], "tone": "professional", "systemPrompt": "You are a marketing expert with 15+ years of experience...", "isDefault": true } } ``` **Error Responses:** - `404 Not Found`: If the role with the specified ID does not exist #### POST /roles Create a new custom role. **Request Body:** ```json { "id": "tech-writer", "name": "Technical Writer", "description": "Specializes in clear, concise technical documentation", "instructions": "Create documentation that is accessible to both technical and non-technical audiences", "domains": ["technical-writing", "documentation", "tutorials"], "tone": "technical", "systemPrompt": "You are an experienced technical writer with expertise in creating clear, concise documentation for complex systems." } ``` **Response:** ```json { "role": { "id": "tech-writer", "name": "Technical Writer", "description": "Specializes in clear, concise technical documentation", "instructions": "Create documentation that is accessible to both technical and non-technical audiences", "domains": ["technical-writing", "documentation", "tutorials"], "tone": "technical", "systemPrompt": "You are an experienced technical writer with expertise in creating clear, concise documentation for complex systems.", "isDefault": false } } ``` **Error Responses:** - `400 Bad Request`: If the request body is invalid or missing required fields - `409 Conflict`: If a role with the specified ID already exists #### PATCH /roles/:roleId Update an existing role. **Parameters:** - `roleId` (path parameter): The ID of the role to update **Request Body:** All fields are optional. Only the fields that are included will be updated. ```json { "name": "Updated Name", "description": "Updated description", "instructions": "Updated instructions", "domains": ["updated-domain"], "tone": "casual", "systemPrompt": "Updated system prompt" } ``` **Response:** ```json { "role": { "id": "tech-writer", "name": "Updated Name", "description": "Updated description", "instructions": "Updated instructions", "domains": ["updated-domain"], "tone": "casual", "systemPrompt": "Updated system prompt", "isDefault": false } } ``` **Error Responses:** - `400 Bad Request`: If the request body is invalid - `404 Not Found`: If the role with the specified ID does not exist - `403 Forbidden`: If attempting to update a default role #### DELETE /roles/:roleId Delete a custom role. **Parameters:** - `roleId` (path parameter): The ID of the role to delete **Response:** ```json { "success": true, "message": "Role deleted successfully" } ``` **Error Responses:** - `404 Not Found`: If the role with the specified ID does not exist - `403 Forbidden`: If attempting to delete a default role ### Query Processing #### POST /process Process a query using a specific role. **Request Body:** ```json { "roleId": "marketing-expert", "query": "How can I improve my social media engagement?", "customInstructions": "Focus on B2B strategies" // Optional } ``` **Response:** ```json { "roleId": "marketing-expert", "query": "How can I improve my social media engagement?", "response": "To improve your social media engagement, especially for B2B..." } ``` **Error Responses:** - `400 Bad Request`: If the request body is invalid or missing required fields - `404 Not Found`: If the role with the specified ID does not exist - `500 Internal Server Error`: If there was an error processing the query ### Tone Profiles #### GET /tones Get all available tone profiles. **Response:** ```json { "tones": { "professional": { "description": "Formal and business-like", "modifiers": "Use formal language, avoid contractions, maintain a serious tone" }, "casual": { "description": "Relaxed and conversational", "modifiers": "Use contractions, simple language, and a friendly tone" }, "technical": { "description": "Precise and detailed", "modifiers": "Use technical terminology, be precise and detailed" }, "creative": { "description": "Imaginative and expressive", "modifiers": "Use metaphors, vivid descriptions, and varied sentence structures" }, "witty": { "description": "Clever and humorous", "modifiers": "Use wordplay, light humor, and clever observations" } } } ``` ### Memory Management #### POST /memories Store a memory for a specific role. **Request Body:** ```json { "roleId": "marketing-expert", "content": "The user prefers Instagram over TikTok for their business", "type": "user", // "session", "user", or "knowledge" "importance": "medium" // "low", "medium", or "high" } ``` **Response:** ```json { "success": true, "memory": { "id": "550e8400-e29b-41d4-a716-446655440000", "roleId": "marketing-expert", "content": "The user prefers Instagram over TikTok for their business", "type": "user", "importance": "medium", "embedding": [...], // Vector embedding "createdAt": "2023-06-01T12:00:00Z", "expiresAt": "2023-07-01T12:00:00Z" } } ``` **Error Responses:** - `400 Bad Request`: If the request body is invalid or missing required fields - `404 Not Found`: If the role with the specified ID does not exist #### GET /memories/:roleId Get memories for a specific role. **Parameters:** - `roleId` (path parameter): The ID of the role to get memories for **Query Parameters:** - `type` (optional): Filter by memory type ("session", "user", or "knowledge") - `limit` (optional): Maximum number of memories to return (default: 10) **Response:** ```json { "memories": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "roleId": "marketing-expert", "content": "The user prefers Instagram over TikTok for their business", "type": "user", "importance": "medium", "createdAt": "2023-06-01T12:00:00Z", "expiresAt": "2023-07-01T12:00:00Z" }, // More memories... ] } ``` **Error Responses:** - `404 Not Found`: If the role with the specified ID does not exist #### DELETE /memories/:roleId Clear all memories for a specific role. **Parameters:** - `roleId` (path parameter): The ID of the role to clear memories for **Query Parameters:** - `type` (optional): Filter by memory type ("session", "user", or "knowledge") **Response:** ```json { "success": true, "message": "Memories cleared successfully" } ``` **Error Responses:** - `404 Not Found`: If the role with the specified ID does not exist ## Error Handling All API endpoints return appropriate HTTP status codes and error messages in case of errors. **Example Error Response:** ```json { "error": { "message": "Role not found", "code": "ROLE_NOT_FOUND" } } ``` ## Rate Limiting Currently, there is no rate limiting implemented. In a production environment, you should implement rate limiting to prevent abuse. ## Versioning The API is currently at version 1.0.0. Future versions may include breaking changes and will be documented accordingly. ## Examples ### Example: Creating a Custom Role ```javascript const axios = require('axios'); async function createCustomRole() { try { const response = await axios.post('http://localhost:3000/roles', { id: "financial-advisor", name: "Financial Advisor", description: "Provides financial planning and investment advice", instructions: "Give balanced financial advice considering risk tolerance and long-term goals", domains: ["finance", "investing", "retirement", "taxes"], tone: "professional", systemPrompt: "You are a certified financial planner with 15+ years of experience helping clients achieve their financial goals." }); console.log('Custom role created:', response.data.role); } catch (error) { console.error('Error creating custom role:', error.response?.data || error.message); } } createCustomRole(); ``` ### Example: Processing a Query ```javascript const axios = require('axios'); async function processQuery() { try { const response = await axios.post('http://localhost:3000/process', { roleId: "marketing-expert", query: "How can I improve my social media engagement?", customInstructions: "Focus on B2B strategies" }); console.log('Response:', response.data.response); } catch (error) { console.error('Error processing query:', error.response?.data || error.message); } } processQuery(); ```