Dev

.github/copilot-instructions.md

@@ -0,0 +1,233 @@
+# Central Memory MCP Server
+
+Model Context Protocol (MCP) memory server built with Azure Functions and TypeScript, providing persistent knowledge graph storage for AI assistants in VS Code.
+
+**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
+
+## Working Effectively
+
+### Bootstrap, Build, and Test the Repository
+
+```bash
+# Install dependencies - takes ~2 seconds
+npm install
+
+# Build the project - takes ~2 seconds. NEVER CANCEL.
+npm run build
+
+# Install Azure Functions Core Tools v4 (if not already installed)
+npm install -g azure-functions-core-tools@4 --unsafe-perm true
+# NOTE: May fail due to firewall limitations - see Alternative Setup below
+```
+
+### Start the Development Environment
+
+**Prerequisites:**
+- Node.js 18+ with npm
+- Azure Functions Core Tools v4
+- Azurite (for local storage)
+
+**Setup Steps:**
+
+1. **Start Azurite Storage Emulator**
+   ```bash
+   # Option 1: Use VS Code extension (recommended)
+   # Install "Azurite" extension and start from command palette
+
+   # Option 2: Command line (if azurite is installed globally)
+   azurite --location ./azurite --debug
+   # NOTE: May fail due to firewall limitations during installation
+   ```
+
+2. **Run the Azure Functions Server**
+   ```bash
+   # Start the server - NEVER CANCEL. Set timeout to 30+ minutes for first run.
+   func start --port 7071 --verbose
+
+   # Alternative: Use npm script
+   npm start
+   ```
+
+3. **Configure VS Code**
+   - Install recommended extensions from `.vscode/extensions.json`
+   - The `.vscode/mcp.json` configures the MCP connection
+   - Use `#memory-test` tools in Copilot chat
+
+### Alternative Setup (Network Restrictions)
+
+If Azure Functions Core Tools or Azurite installation fails due to network/firewall limitations:
+
+1. **Document the limitation**: "Azure Functions Core Tools installation fails due to firewall limitations"
+2. **Use Docker alternative**: The repository includes a `Dockerfile` for containerized development
+   ```bash
+   # Build the container - takes 10+ minutes. NEVER CANCEL. Set timeout to 20+ minutes.
+   docker build -t central-memory-mcp .
+
+   # Run the container 
+   docker run -p 7071:80 central-memory-mcp
+   ```
+3. **Use health endpoints for validation**: The application provides `/api/health` and `/api/ready` endpoints
+4. **Manual testing approach**: Build the project and examine the `dist/` folder structure
+5. **Focus on build validation**: Ensure `npm run build` succeeds and produces correct output
+
+## Validation
+
+### Manual Validation Steps
+
+**ALWAYS run through these validation scenarios after making changes:**
+
+1. **Build Validation**
+   ```bash
+   npm run build
+   # Verify dist/ folder is created with proper structure
+   ls -la dist/
+   ```
+
+2. **Health Check Validation** (if func is available)
+   ```bash
+   # Start the server (if possible)
+   func start --port 7071
+
+   # Test health endpoint
+   curl http://localhost:7071/api/health
+
+   # Test readiness endpoint  
+   curl http://localhost:7071/api/ready
+   ```
+
+3. **MCP Tools Testing** (in VS Code with Copilot)
+   ```text
+   # Create an entity
+   #memory-test_create_entities workspaceId="my-project" entities={"name": "Alice", "entityType": "Person", "observations": ["Software engineer"]}
+
+   # Create a relation
+   #memory-test_create_relations workspaceId="my-project" relations={"from": "Alice", "to": "React Project", "relationType": "worksOn"}
+
+   # Search entities
+   #memory-test_search_entities workspaceId="my-project" name="Alice"
+
+   # Read the graph
+   #memory-test_read_graph workspaceId="my-project"
+   ```
+
+4. **File Structure Validation**
+   ```bash
+   # Verify all key components are present
+   ls -la src/functions/    # mcpTools.ts, health.ts, ready.ts
+   ls -la src/services/     # entities.ts, relations.ts, stats.ts, storageService.ts
+   ls -la src/types/        # TypeScript definitions
+   ```
+
+### CRITICAL Build and Test Timing
+
+- **npm install**: Takes ~2 seconds. NEVER CANCEL.
+- **npm run build**: Takes ~2 seconds. NEVER CANCEL.
+- **func start**: Takes 30+ seconds for first run. NEVER CANCEL. Set timeout to 30+ minutes.
+- **docker build**: Takes 10+ minutes for first build. NEVER CANCEL. Set timeout to 20+ minutes.
+- **Health endpoints**: Respond within 5 seconds when running.
+
+**NEVER CANCEL BUILDS OR LONG-RUNNING COMMANDS** - Azure Functions may take several minutes to start properly.
+
+## Common Tasks
+
+### Repository Structure
+
+```text
+├── .docs/              # Comprehensive documentation
+│   ├── ARCHITECTURE.md # Technical design patterns
+│   ├── API.md         # Complete MCP tools reference  
+│   ├── STORAGE.md     # Storage configuration guide
+│   └── DEPLOYMENT.md  # Production deployment options
+├── .github/           # GitHub configuration
+├── .vscode/           # VS Code integration config
+│   ├── extensions.json # Recommended extensions
+│   └── mcp.json       # MCP server configuration
+├── src/
+│   ├── functions/     # Azure Functions endpoints
+│   │   ├── mcpTools.ts # 16 MCP tools for knowledge graph
+│   │   ├── health.ts   # Health check endpoint
+│   │   └── ready.ts    # Readiness probe
+│   ├── services/      # Business logic
+│   │   ├── entities.ts    # Entity operations
+│   │   ├── relations.ts   # Relationship operations  
+│   │   ├── stats.ts       # Graph statistics and batch ops
+│   │   ├── storageService.ts # Azure Table Storage abstraction
+│   │   ├── logger.ts      # Structured logging
+│   │   └── utils.ts       # Utility functions
+│   ├── types/         # TypeScript definitions
+│   └── index.ts       # Main entry point
+├── dist/              # Compiled JavaScript (after build)
+├── package.json       # Dependencies and scripts
+├── host.json          # Azure Functions configuration
+├── tsconfig.json      # TypeScript configuration
+└── Dockerfile         # Container deployment
+```
+
+### Key Configuration Files
+
+**package.json scripts:**
+- `build` - Compile TypeScript to JavaScript
+- `start` - Start Azure Functions runtime
+
+**Environment Variables (Development):**
+```bash
+AzureWebJobsStorage=UseDevelopmentStorage=true
+```
+
+**Environment Variables (Production):**
+```bash
+AzureWebJobsStorage=DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=...
+AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
+```
+
+### Frequently Used Commands
+
+```bash
+# Quick development cycle
+npm install && npm run build
+
+# Check application structure  
+find src -name "*.ts" | head -15
+
+# Verify build output
+ls -la dist/functions/
+
+# Check package info
+cat package.json | grep -E "(name|version|scripts)"
+```
+
+### Important Code Locations
+
+- **MCP Tools Registration**: `src/functions/mcpTools.ts` - All 16 MCP tools with object parameters
+- **Storage Layer**: `src/services/storageService.ts` - Azure Table Storage with workspace isolation
+- **Entity Operations**: `src/services/entities.ts` - Create, search, update entities
+- **Relation Operations**: `src/services/relations.ts` - Create, search relations  
+- **Health Endpoints**: `src/functions/health.ts` and `src/functions/ready.ts`
+
+### Development Notes
+
+- **Workspace Isolation**: Each project gets separate storage via workspaceId parameter
+- **MCP Integration**: All tools use object parameters (not JSON strings) for better type safety
+- **Storage**: Uses Azure Table Storage with Azurite for local development
+- **Logging**: Structured logging with correlation IDs throughout the application
+- **Error Handling**: Comprehensive error handling with proper MCP protocol responses
+
+### Troubleshooting
+
+**Build Issues:**
+- Ensure Node.js 18+ is installed
+- Run `npm install` before `npm run build`
+- Check `tsconfig.json` for TypeScript configuration
+
+**Runtime Issues:**
+- Verify Azurite is running for local development
+- Check `host.json` for function timeout settings (currently 5 minutes)
+- Use health endpoints to verify service status
+
+**Network/Firewall Issues:**
+- Azure Functions Core Tools installation may fail - document the limitation: "Azure Functions Core Tools installation fails due to firewall/network limitations"
+- Azurite installation may fail - use Docker alternative or document limitation  
+- Health endpoint testing may not be possible - focus on build validation
+- **WORKAROUND**: If `func start` is not available, validate by examining build output in `dist/` folder and ensuring TypeScript compilation succeeds
+
+**Always check handler.ts after making changes to any service files in src/services/.**

.gitignore

@@ -164,3 +164,4 @@ dist
 
 data
 AzuriteConfig
+/.idea/

.vscode/mcp.json

@@ -1,27 +1,30 @@
 {
-    "servers": {
-        "context7": {
-            "type": "http",
-            "url": "https://mcp.context7.com/mcp"
-        },
-        "microsoft.docs.mcp": {
-            "type": "http",
-            "url": "https://learn.microsoft.com/api/mcp"
-        },
-        "sequential-thinking": {
-            "command": "npx",
-            "args": [
-                "-y",
-                "@modelcontextprotocol/server-sequential-thinking"
-            ]
-        },
-        "memory-debug": {
-            "type": "http",
-            "url": "http://localhost:7071/runtime/webhooks/mcp/sse?workspace=Central-Memory-MCP"
-        },
-        "memory-prod": {
-			"type": "http",
-			"url": "https://yourfunctionapp.azurewebsites.net/runtime/webhooks/mcp/sse?workspace=Central-Memory-MCP&code=yourMcpExtensionKey"
-		}
+  "inputs": [
+    {
+      "id": "context7-mcp-api-key",
+      "description": "Context7 MCP API Key",
+      "type": "promptString",
+      "password": true
     }
+  ],
+  "servers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "${input:context7-mcp-api-key}"
+      }
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "memory-debug": {
+      "type": "http",
+      "url": "http://localhost:7071/runtime/webhooks/mcp"
+    }
+  }
 }

README.md

@@ -1,4 +1,5 @@
 # Central Memory MCP Server
+[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/MWGMorningwood/Central-Memory-MCP)](https://archestra.ai/mcp-catalog/mwgmorningwood__central-memory-mcp)
 
 Model Context Protocol (MCP) memory server built with Azure Functions and TypeScript, providing persistent knowledge graph storage for AI assistants in VS Code.  
 Inspired by and forked from [`@modelcontextprotocol/server-memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)
@@ -32,31 +33,53 @@ curl http://localhost:7071/api/health
 
 ### Example Usage in VS Code Copilot
 
+**Recommended workflow for best results:**
+
 ```text
-Create an entity:
+1. First, check existing data:
+#memory-test_read_graph workspaceId="my-project"
+
+2. Search for existing entities:
+#memory-test_search_entities workspaceId="my-project" name="Alice"
+
+3. Create entities (auto-updates existing ones):
 #memory-test_create_entities workspaceId="my-project" entities={"name": "Alice", "entityType": "Person", "observations": ["Software engineer"]}
 
-Create a relation:
+4. Create relationships (auto-creates missing entities):
 #memory-test_create_relations workspaceId="my-project" relations={"from": "Alice", "to": "React Project", "relationType": "worksOn"}
 
-Search entities:
-#memory-test_search_entities workspaceId="my-project" name="Alice"
+5. Add observations (auto-creates entity if missing):
+#memory-test_add_observation workspaceId="my-project" entityName="Alice" observation="Leads the frontend team" entityType="Person"
 ```
 
+**Key Features for Better LLM Usability:**
+- ✅ Auto-creation of missing entities when adding observations or relations
+- ✅ Helpful error messages with examples when validation fails  
+- ✅ Workflow guidance to view graph first, then search, then create
+- ✅ Clear parameter descriptions with expected formats
+- ✅ Reduced friction - tools handle common edge cases automatically
+
 ## 🔧 MCP Tools
 
 **Core Operations:**
 
-- `create_entities` - Create single entity with observations
-- `create_relations` - Create single relationship between entities
-- `read_graph` - Read the entire knowledge graph
-- `search_entities` / `search_relations` - Search by name/type
-- `add_observation` - Add observations to existing entities
+- `read_graph` - **RECOMMENDED FIRST STEP**: View the entire knowledge graph to understand existing data
+- `create_entities` - Create entities with auto-update of existing ones
+- `create_relations` - Create relationships with auto-creation of missing entities  
+- `search_entities` / `search_relations` - Search and verify existing data
+- `add_observation` - Add observations with auto-creation of missing entities
 - `update_entity` - Update entity observations and metadata
 - `delete_entity` - Remove entity and all its relations
 - `get_stats` - Get workspace statistics
 - `clear_memory` - Clear all workspace data
 
+**Recommended Workflow:**
+1. Use `read_graph` to understand existing data
+2. Use `search_entities` to check for existing entities
+3. Use `create_entities` to add new entities
+4. Use `create_relations` to connect entities
+5. Use `add_observation` to add new information
+
 **Advanced Features:**
 
 - `get_temporal_events` - Time-based activity tracking

host.json

@@ -16,7 +16,7 @@
     }
   },
   "extensionBundle": {
-    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
+    "id": "Microsoft.Azure.Functions.ExtensionBundle.Experimental",
     "version": "[4.*, 5.0.0)"
   },
   "functionTimeout": "00:05:00"