feat: finalize local OpenAI key flow and MCP docs

- add server-side .env.local OpenAI key management for the open-source app
- route AI features through the preferred local key path and lazy-load embed recovery
- rewrite README and docs for current MCP setup, schema, and fully-local guidance

Generated with Claude Code

src/services/database/descriptionService.ts

@@ -1,6 +1,6 @@
 import { generateText } from 'ai';
-import { openai as openaiProvider } from '@ai-sdk/openai';
-import { hasValidOpenAiKey } from '../storage/apiKeys';
+import { createOpenAI } from '@ai-sdk/openai';
+import { hasPreferredOpenAiKey, getPreferredOpenAiKey } from '../storage/openaiKeyServer';
 import type { CanonicalNodeMetadata } from '@/types/database';
 
 export interface DescriptionInput {
@@ -23,7 +23,7 @@ export interface DescriptionInput {
  * The result must cover what the artifact is, why it is in the graph, and workflow status.
  */
 export async function generateDescription(input: DescriptionInput): Promise<string> {
-  if (!hasValidOpenAiKey()) {
+  if (!hasPreferredOpenAiKey()) {
     console.log(`[DescriptionService] No valid OpenAI key, using fallback for: "${input.title}"`);
     return `${input.title}. Added via Quick Add with no further context yet, so the reason it belongs in the graph is not fully inferred. It has not been reviewed yet.`.slice(0, 500);
   }
@@ -33,8 +33,9 @@ export async function generateDescription(input: DescriptionInput): Promise<stri
 
     console.log(`[DescriptionService] Generating description for: "${input.title}"`);
 
+    const provider = createOpenAI({ apiKey: getPreferredOpenAiKey() });
     const response = await generateText({
-      model: openaiProvider('gpt-4o-mini'),
+      model: provider('gpt-4o-mini'),
       prompt,
       maxOutputTokens: 100,
       temperature: 0.3,
@@ -52,8 +53,6 @@ export async function generateDescription(input: DescriptionInput): Promise<stri
   }
 }
 
-export { hasValidOpenAiKey } from '../storage/apiKeys';
-
 function buildDescriptionPrompt(input: DescriptionInput): string {
   const sourceMetadata = input.metadata?.source_metadata as Record<string, unknown> | undefined;
   const sourceType = typeof input.metadata?.type === 'string'

src/services/database/edges.ts

@@ -3,10 +3,10 @@ import { Edge, EdgeContext, EdgeData, EdgeCreatedVia, NodeConnection, Node } fro
 import { eventBroadcaster } from '../events';
 import { nodeService } from './nodes';
 import { generateText } from 'ai';
-import { openai } from '@ai-sdk/openai';
+import { createOpenAI } from '@ai-sdk/openai';
 import { z } from 'zod';
 import { validateEdgeExplanation } from './quality';
-import { hasValidOpenAiKey } from '../storage/apiKeys';
+import { getPreferredOpenAiKey, hasPreferredOpenAiKey } from '../storage/openaiKeyServer';
 
 const inferredEdgeContextSchema = z.object({
   type: z.enum(['created_by', 'part_of', 'source_of', 'related_to']),
@@ -75,12 +75,13 @@ async function inferEdgeContext(params: {
   ].join('\n');
 
   try {
-    if (!hasValidOpenAiKey()) {
+    if (!hasPreferredOpenAiKey()) {
       return { type: 'related_to', confidence: 0.2, swap_direction: false };
     }
 
+    const provider = createOpenAI({ apiKey: getPreferredOpenAiKey() });
     const { text } = await generateText({
-      model: openai('gpt-4o-mini'),
+      model: provider('gpt-4o-mini'),
       prompt,
       temperature: 0.0,
       maxOutputTokens: 120,
@@ -141,7 +142,7 @@ async function autoInferEdge(params: {
   ].join('\n');
 
   try {
-    if (!hasValidOpenAiKey()) {
+    if (!hasPreferredOpenAiKey()) {
       return {
         explanation: `Connection to ${toNode.title}; exact relationship uncertain.`,
         type: 'related_to',
@@ -150,8 +151,9 @@ async function autoInferEdge(params: {
       };
     }
 
+    const provider = createOpenAI({ apiKey: getPreferredOpenAiKey() });
     const { text } = await generateText({
-      model: openai('gpt-4o-mini'),
+      model: provider('gpt-4o-mini'),
       prompt,
       temperature: 0.0,
       maxOutputTokens: 150,