Skip to content

Commit fb24ba2

Browse files
thegovindthegovind
authored
Merge pull request #20 from Azure-Samples/gk/deep-wiki-updates
improve tool property descriptions
2 parents 5114ff7 + b178c23 commit fb24ba2

File tree

4 files changed

+499
-358
lines changed

4 files changed

+499
-358
lines changed

‎.github/assets/snippy-architecture.png‎

39.8 KB
Loading

‎README.md‎

Lines changed: 42 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!--
22
---
33
name: Snippy - Intelligent Code Snippet Service with MCP Tools
4-
description: A serverless code snippet management service using Azure Functions, Durable Functions, Azure OpenAI, and Azure AI Agents.
4+
description: A serverless code snippet management service using Azure Functions, Durable Functions, Azure OpenAI, Microsoft Fabric and Azure AI Agents.
55
page_type: sample
66
languages:
77
- python
@@ -14,6 +14,7 @@ products:
1414
- azure-cosmos-db
1515
- azure-ai-projects
1616
- azure-ai-agents
17+
- fabric
1718
urlFragment: snippy
1819
---
1920
-->
@@ -32,8 +33,10 @@ Snippy is an **Azure Functions**–based reference application that turns any fu
3233

3334
* **Save snippets** – persists code, metadata and OpenAI embeddings in **Cosmos DB DiskANN**
3435
* **Semantic retrieve** – vector search over embeddings
35-
* **AI Agents** – generate a deep wiki or language‑specific style guide from stored snippets
36+
* **AI Agents** – generate a **deep wiki** or language‑specific **code style guide** from stored snippets
3637
* **Durable fan‑out/fan‑in with Blueprints** – [in experimental branch](https://github.com/Azure-Samples/snippy/tree/gk/durable-functions) for large‑scale processing
38+
* **Microsoft Fabric integration** – [in gk/fabric branch](https://github.com/Azure-Samples/snippy/tree/gk/fabric) demonstrating how to build Agents with Fabric Data Agents
39+
3740

3841
The project ships with reproducible **azd** infrastructure, so `azd up` will stand up the entire stack – Functions, Cosmos DB, Azure OpenAI and Azure AI Agents – in a single command.
3942

@@ -72,22 +75,43 @@ The project ships with reproducible **azd** infrastructure, so `azd up` will st
7275
![Snippy Architecture](https://raw.githubusercontent.com/Azure-Samples/snippy/main/.github/assets/snippy-architecture.png)
7376

7477
```mermaid
75-
graph TD
76-
User[Human / Copilot Chat] -->|HTTP / MCP| FnApp[Azure Functions\nSnippy]
77-
78-
subgraph Functions
79-
Save[save_snippet] -- embeddings --> AOAI
80-
Save -- JSON --> Cosmos
81-
Get[get_snippet] --> Cosmos
82-
Wiki[deep_wiki] -- vector search --> Cosmos
83-
Wiki --> Agents
84-
Style[code_style] -- vector search --> Cosmos
85-
Style --> Agents
86-
end
87-
88-
AOAI[Azure OpenAI]
89-
Cosmos[(Cosmos DB DiskANN)]
90-
Agents[Azure AI Agents]
78+
flowchart LR
79+
%% ─── MCP Hosts & Clients (local) ──────────────────────────────
80+
subgraph mcphosts["MCP Hosts & Clients (Your Computer)"]
81+
Host["Host<br/>(VS Code / IDE)"]
82+
Client["Client<br/>(GitHub Copilot)"]
83+
end
84+
85+
%% ─── Application on Azure (remote) ────────────────────────────
86+
subgraph app["Application (Azure)"]
87+
Snippy["MCP Server<br/>Snippy Triggers<br/>(Function App)"]:::dashed
88+
Foundry["Foundry Agent<br/>Deep Wiki · Code Style"]
89+
Cosmos["Cosmos DB<br/>Operational + Vector DB"]:::datasource
90+
AOAI["Azure OpenAI<br/>text‑embedding‑3‑small"]
91+
FabricDA["Fabric – Data Agent"]
92+
VectorTool["Tools – Vector Search"]
93+
end
94+
95+
%% ─── Local interactions ───────────────────────────────────────
96+
Host <--> Client
97+
98+
%% ─── MCP protocol to Azure ────────────────────────────────────
99+
Client <-- "MCP Protocol (SSE)" --> Snippy
100+
101+
%% ─── Bindings & data flow inside Azure ────────────────────────
102+
Snippy -- Bindings --> AOAI
103+
Snippy --> Cosmos
104+
Snippy --> Foundry
105+
Foundry --> FabricDA
106+
Foundry --> VectorTool
107+
108+
%% ─── Styling ──────────────────────────────────────────────────
109+
classDef datasource stroke-width:2,stroke-dasharray:5 5
110+
classDef dashed stroke-width:2,stroke-dasharray:5 5,fill:transparent
111+
class Cosmos datasource
112+
class Snippy dashed
113+
style mcphosts fill:transparent
114+
style app fill:transparent
91115
```
92116

93117
---

‎deep-wiki.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Project Overview
2+
3+
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.
4+
5+
## Major Concepts
6+
7+
### MCP Tools
8+
9+
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.
10+
11+
### Azure Functions
12+
13+
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.
14+
15+
### Cosmos DB & Vector Search
16+
17+
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.
18+
19+
### Azure OpenAI
20+
21+
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.
22+
23+
### Error Handling & Logging
24+
25+
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.
26+
27+
### Bicep Templates
28+
29+
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.
30+
31+
## Diagram Visualizations
32+
33+
### System Architecture
34+
35+
```mermaid
36+
flowchart TB
37+
subgraph Azure Services
38+
AzureFunctions --Triggers--> MCPTools
39+
MCPTools --Stores--> CosmosDB
40+
MCPTools --Generates--> AzureOpenAI
41+
end
42+
43+
subgraph MCPTool Interaction
44+
SaveSnippet --Embeds--> AzureOpenAI
45+
GetSnippet --Reads--> CosmosDB
46+
end
47+
48+
AzureFunctions -.-> Logging
49+
Logging -.-> ErrorHandling
50+
```
51+
52+
### Data Flow
53+
54+
```mermaid
55+
sequenceDiagram
56+
participant User
57+
participant AzureFunctionApp
58+
participant AzureOpenAI
59+
participant CosmosDB
60+
61+
User->>AzureFunctionApp: Send Snippet
62+
AzureFunctionApp->>AzureOpenAI: Generate Embeddings
63+
AzureOpenAI-->>AzureFunctionApp: Return Embeddings
64+
AzureFunctionApp->>CosmosDB: Store Snippet & Embeddings
65+
CosmosDB-->>AzureFunctionApp: Success/Failure Response
66+
AzureFunctionApp-->>User: Notify Status
67+
```
68+
69+
## Snippet Catalog
70+
71+
| Snippet ID | Language | Purpose |
72+
|--------------------------|-------------|---------------------------------------------------|
73+
| snip-func | Python | MCP tool trigger for saving snippets |
74+
| func-app-snippy | Python | Demonstrates Azure Functions with multiple services|
75+
| main-bicep | Bicep | Infrastructure as code for Azure provisioning |
76+
| test-snippet-default-project | Python | Simple print function |
77+
| complex-snippet-default | Python | Basic Calculator class |
78+
79+
## Walkthroughs
80+
81+
### Saving a Snippet
82+
83+
1. **Send HTTP Request**: Utilize Azure Function to POST a code snippet.
84+
- Include required fields such as name and code.
85+
2. **Generate Embeddings**: Azure OpenAI generates vector embeddings from code.
86+
3. **Store in CosmosDB**: Snippet and embeddings are stored as a document.
87+
4. **Logging & Error Handling**: Any errors during the procedure are logged and conveyed back to the user.
88+
89+
### Provisioning Resources
90+
91+
1. **Define Configuration**: Use Bicep templates to specify parameters and resources.
92+
2. **Deploy Resources**: Execute the Bicep script to allocate Azure resources.
93+
3. **Output Configuration**: Retrieve necessary configuration values post-deployment.
94+
95+
## Best Practices
96+
97+
- Ensure all Azure Function triggers are well-defined to avoid unexpected invocation issues.
98+
- Use robust error handling to manage unforeseen runtime exceptions.
99+
- Structure logging to capture crucial operational details for later analysis.
100+
- Secure Bicep templates to prevent exposure of sensitive data and secrets.
101+
102+
## Anti-patterns
103+
104+
- Avoid hardcoding API keys in the code; use secure environment variables instead.
105+
- Do not neglect validation of user input, which can lead to errors in processing.
106+
107+
## Open TODOs
108+
109+
- Implement a more granular logging system for detailed telemetry.
110+
- Enhance support for additional programming languages beyond Python.
111+
- Expand the capabilities of vector search to support more complex queries.
112+
113+
## Further Reading
114+
115+
- [Azure Functions Documentation](https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference)
116+
- [Cosmos DB Documentation](https://docs.microsoft.com/en-us/azure/cosmos-db/introduction)
117+
- [Azure Bicep Documentation](https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep)
118+
- [Azure OpenAI Documentation](https://docs.microsoft.com/en-us/azure/cognitive-services/openai/overview)
119+
120+
This documentation provides a comprehensive overview of the MCP tools project, detailing its architecture, functionality, and best practices.

0 commit comments

Comments
 (0)