Dedalus MCP Documentation Server

Instructions

Answer questions about documentation using AI

Args:
    question: The question to answer
    context_docs: Optional list of document paths to use as context
    max_context_length: Maximum characters of context to include
    user_id: Optional user identifier for rate limiting

Returns:
    AI-generated answer with sources

Implementation Reference

• src/main.py:269-394 (handler)

  The primary handler function for the 'ask_docs' MCP tool. Decorated with @mcp.tool() for automatic schema generation and registration. Implements rate limiting, automatic context retrieval via search_docs if needed, context truncation, OpenAI GPT-4o-mini integration for answer generation (with fallback to raw context provision if no API key), source tracking, and comprehensive error handling.

  @mcp.tool()
  def ask_docs(
      question: str,
      context_docs: Optional[List[str]] = None,
      max_context_length: int = 4000,
      user_id: Optional[str] = None,
  ) -> Dict[str, Any]:
      """
      Answer questions about documentation using AI
  
      Args:
          question: The question to answer
          context_docs: Optional list of document paths to use as context
          max_context_length: Maximum characters of context to include
          user_id: Optional user identifier for rate limiting
  
      Returns:
          AI-generated answer with sources
      """
      # Rate limiting check
      identifier = user_id or 'default'
      if not rate_limiter.is_allowed(identifier):
          reset_time = rate_limiter.get_reset_time(identifier)
          return {
              'error': 'Rate limit exceeded',
              'message': f'Too many requests. Please wait {reset_time} seconds before trying again.',
              'reset_in_seconds': reset_time,
              'limit': '10 requests per minute',
          }
      # If no context docs specified, search for relevant ones
      if not context_docs:
          search_results = search_docs(question, max_results=3)
          context_docs = [result['path'] for result in search_results]
  
      # Gather context from documents
      context_parts = []
      sources = []
      total_length = 0
  
      for doc_path in context_docs:
          if total_length >= max_context_length:
              break
  
          try:
              file_path = DOCS_DIR / doc_path
              content = file_path.read_text()
  
              # Truncate if needed
              remaining = max_context_length - total_length
              if len(content) > remaining:
                  content = content[:remaining] + '...'
  
              context_parts.append(f'--- {doc_path} ---\n{content}')
              sources.append(doc_path)
              total_length += len(content)
          except (OSError, UnicodeDecodeError):
              continue
  
      if not context_parts:
          return {
              'answer': "I couldn't find relevant documentation to answer your question.",
              'sources': [],
              'confidence': 'low',
          }
  
      full_context = '\n\n'.join(context_parts)
  
      # Try to use OpenAI if API key is available
      api_key = os.getenv('OPENAI_API_KEY')
      if api_key:
          try:
              from openai import OpenAI
  
              client = OpenAI(api_key=api_key)
  
              response = client.chat.completions.create(
                  model='gpt-4o-mini',
                  messages=[
                      {
                          'role': 'system',
                          'content': 'You are a helpful assistant that answers questions based on provided documentation. Only use information from the provided context.',
                      },
                      {
                          'role': 'user',
                          'content': f"""Based on the following documentation, please answer this question: {question}
  
  Documentation:
  {full_context}
  
  Please provide a clear, concise answer based only on the provided documentation.""",
                      },
                  ],
                  temperature=0.7,
                  max_tokens=500,
              )
  
              return {
                  'answer': response.choices[0].message.content,
                  'sources': sources,
                  'context_length': total_length,
                  'model': 'gpt-4o-mini',
                  'confidence': 'high',
              }
          except Exception as e:
              # Fall back to context-only response if OpenAI fails
              return {
                  'answer': f'Error using OpenAI: {str(e)}',
                  'context': full_context[:500] + '...'
                  if len(full_context) > 500
                  else full_context,
                  'sources': sources,
                  'context_length': total_length,
                  'error': str(e),
              }
  
      # If no API key, return context for Dedalus deployment
      return {
          'question': question,
          'context': full_context[:500] + '...'
          if len(full_context) > 500
          else full_context,
          'sources': sources,
          'context_length': total_length,
          'note': "No API key found. When deployed to Dedalus, this will use the platform's LLM integration via BYOK",
      }

• src/main.py:270-287 (schema)

  Function signature and docstring defining the input schema (question: str, context_docs: Optional[List[str]], etc.) and output format (Dict with answer, sources, etc.). Used by MCP framework for tool schema validation.

  def ask_docs(
      question: str,
      context_docs: Optional[List[str]] = None,
      max_context_length: int = 4000,
      user_id: Optional[str] = None,
  ) -> Dict[str, Any]:
      """
      Answer questions about documentation using AI
  
      Args:
          question: The question to answer
          context_docs: Optional list of document paths to use as context
          max_context_length: Maximum characters of context to include
          user_id: Optional user identifier for rate limiting
  
      Returns:
          AI-generated answer with sources
      """

• src/main.py:42-54 (registration)

  The 'ask_docs' tool is documented and listed as available in the MCP server's instructions string, confirming its registration among available tools.

      instructions="""This MCP server provides access to documentation files with AI-powered search and Q&A capabilities.
      
  Available tools:
  - list_docs(): List all documentation files
  - search_docs(query): Search documentation with keywords
  - ask_docs(question): Get AI-powered answers from documentation
  - index_docs(): Index documents for better search
  - analyze_docs(task): Analyze documentation for specific tasks
  
  Resources:
  - docs://{path}: Access any markdown documentation file directly
  
  This server includes rate limiting (10 requests/minute) to protect API keys.""",

• src/main.py:89-119 (helper)

  RateLimiter class used by ask_docs for API protection (10 req/min).

  class RateLimiter:
      """Simple rate limiter to protect API keys from abuse"""
  
      def __init__(self, max_requests: int = 10, window_seconds: int = 60):
          self.max_requests = max_requests
          self.window_seconds = window_seconds
          self.requests = defaultdict(list)
  
      def is_allowed(self, identifier: str) -> bool:
          """Check if request is allowed for this identifier"""
          now = time.time()
          # Clean old requests outside window
          self.requests[identifier] = [
              req_time
              for req_time in self.requests[identifier]
              if now - req_time < self.window_seconds
          ]
  
          # Check if under limit
          if len(self.requests[identifier]) < self.max_requests:
              self.requests[identifier].append(now)
              return True
          return False
  
      def get_reset_time(self, identifier: str) -> int:
          """Get seconds until rate limit resets"""
          if not self.requests[identifier]:
              return 0
          oldest = min(self.requests[identifier])
          return max(0, int(self.window_seconds - (time.time() - oldest)))

• src/main.py:125-150 (helper)

  get_doc_metadata helper used indirectly via search_docs for document information.

  def get_doc_metadata(file_path: Path) -> Dict[str, Any]:
      """Extract metadata from markdown files"""
      if file_path in METADATA_CACHE:
          return METADATA_CACHE[file_path]
  
      metadata = {
          'title': file_path.stem.replace('-', ' ').title(),
          'path': str(file_path.relative_to(DOCS_DIR)),
          'modified': datetime.fromtimestamp(file_path.stat().st_mtime).isoformat(),
          'size': file_path.stat().st_size,
          'hash': hashlib.md5(file_path.read_bytes()).hexdigest(),
      }
  
      # Try to extract title from first # heading
      try:
          content = file_path.read_text()
          lines = content.split('\n')
          for line in lines[:10]:  # Check first 10 lines
              if line.startswith('# '):
                  metadata['title'] = line[2:].strip()
                  break
      except (OSError, UnicodeDecodeError):
          pass
  
      METADATA_CACHE[file_path] = metadata
      return metadata