Skip to content

deep-wiki.md

Latest commit

 

History

History
120 lines (82 loc) · 5.4 KB

deep-wiki.md

File metadata and controls

120 lines (82 loc) · 5.4 KB

Project Overview

This project is centered around the MCP (Model Context Protocol) tools designed for use with Azure Functions and AI-powered operations. The tools enable seamless integration with Azure OpenAI, Cosmos DB, and AI Agents to manage and analyze code snippets. Key functionalities include document management, vector search, error handling, logging, and provisioned cloud infrastructure using Bicep templates.

Major Concepts

MCP Tools

MCP tools automate operations related to code snippets using triggers that respond to Azure Function events. Tools such as save_snippet, get_snippet, deep_wiki, and code_style interact with various Azure services to provide a robust solution for code documentation and analysis.

Azure Functions

Azure Functions provide the backbone for serverless execution, handling multiple types of triggers including HTTP and custom MCP triggers. The project leverages Azure Functions to perform backend operations with minimal infrastructure overhead.

Cosmos DB & Vector Search

Cosmos DB is employed for document storage, utilizing its ability to handle JSON data. The integration includes vector search capabilities to enhance the retrieval process using embeddings generated by Azure OpenAI.

Azure OpenAI

The project uses Azure OpenAI for advanced AI operations, particularly embedding text for vector-based searches and analysis. This enables intelligent handling and querying of code snippets.

Error Handling & Logging

Error handling in the project is robust, utilizing Python's exception handling capabilities. Logging is crucial for diagnostics and is employed throughout the code to track operations and errors.

Bicep Templates

Azure Bicep is used to define infrastructure as code, setting up Azure resources required for the operation of MCP tools. This involves complex parameter definitions and resource orchestration.

Diagram Visualizations

System Architecture

flowchart TB
    subgraph Azure Services
        AzureFunctions --Triggers--> MCPTools
        MCPTools --Stores--> CosmosDB
        MCPTools --Generates--> AzureOpenAI
    end

    subgraph MCPTool Interaction
        SaveSnippet --Embeds--> AzureOpenAI
        GetSnippet --Reads--> CosmosDB
    end

    AzureFunctions -.-> Logging
    Logging -.-> ErrorHandling
Loading

Data Flow

sequenceDiagram
    participant User
    participant AzureFunctionApp
    participant AzureOpenAI
    participant CosmosDB

    User->>AzureFunctionApp: Send Snippet
    AzureFunctionApp->>AzureOpenAI: Generate Embeddings
    AzureOpenAI-->>AzureFunctionApp: Return Embeddings
    AzureFunctionApp->>CosmosDB: Store Snippet & Embeddings
    CosmosDB-->>AzureFunctionApp: Success/Failure Response
    AzureFunctionApp-->>User: Notify Status
Loading

Snippet Catalog

Snippet ID Language Purpose
snip-func Python MCP tool trigger for saving snippets
func-app-snippy Python Demonstrates Azure Functions with multiple services
main-bicep Bicep Infrastructure as code for Azure provisioning
test-snippet-default-project Python Simple print function
complex-snippet-default Python Basic Calculator class

Walkthroughs

Saving a Snippet

  1. Send HTTP Request: Utilize Azure Function to POST a code snippet.
    • Include required fields such as name and code.
  2. Generate Embeddings: Azure OpenAI generates vector embeddings from code.
  3. Store in CosmosDB: Snippet and embeddings are stored as a document.
  4. Logging & Error Handling: Any errors during the procedure are logged and conveyed back to the user.

Provisioning Resources

  1. Define Configuration: Use Bicep templates to specify parameters and resources.
  2. Deploy Resources: Execute the Bicep script to allocate Azure resources.
  3. Output Configuration: Retrieve necessary configuration values post-deployment.

Best Practices

  • Ensure all Azure Function triggers are well-defined to avoid unexpected invocation issues.
  • Use robust error handling to manage unforeseen runtime exceptions.
  • Structure logging to capture crucial operational details for later analysis.
  • Secure Bicep templates to prevent exposure of sensitive data and secrets.

Anti-patterns

  • Avoid hardcoding API keys in the code; use secure environment variables instead.
  • Do not neglect validation of user input, which can lead to errors in processing.

Open TODOs

  • Implement a more granular logging system for detailed telemetry.
  • Enhance support for additional programming languages beyond Python.
  • Expand the capabilities of vector search to support more complex queries.

Further Reading

This documentation provides a comprehensive overview of the MCP tools project, detailing its architecture, functionality, and best practices.