AI导哈

知识后端服务

Uncover Learning的知识后端系统，通过结合屏幕覆盖、LLM推理和结构化文档数据库，教授用户如何使用软件。

  • by HD1972
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 HD1972/Figma-MCP

使用说明

Uncover Learning – Knowledge Backend

Knowledge backend for Uncover Learning, a system that teaches users how to use software by combining screen overlays, LLM reasoning, and a structured documentation database.

Architecture

This repository contains:

  1. Firestore data model - Structured collections for apps, tasks, steps, UI screens, elements, and documentation
  2. Firebase Storage - File storage for screenshots, images, and other files
  3. TypeScript types - Type-safe interfaces for all data structures
  4. Service functions - Query functions that will be exposed as MCP tools or HTTP endpoints
  5. Seed scripts - Load JSON data into Firestore

Project Structure

.
├── src/
│   ├── types/          # TypeScript interfaces for Firestore documents
│   ├── firebase/       # Firebase Admin SDK initialization
│   ├── data/           # Loaders/parsers for local JSON files
│   ├── services/       # Firestore query logic (MCP tools)
│   └── scripts/        # One-off scripts (e.g., seeding)
├── data/               # Local JSON seed data
│   └── figma/          # Example app data
│       ├── app.json
│       ├── tasks/
│       ├── taskSteps/
│       ├── uiScreens/
│       ├── uiElements/
│       └── docSections/
└── dist/               # Compiled TypeScript output

Setup

  1. Install dependencies:

    npm install

  2. Configure Firebase:

    • Set up Firebase project
    • Create .env.local file (copy from env.local.template):
      # Required: Your Firebase project ID
FIREBASE_PROJECT_ID=your-project-id-here

# Option 1: Service account JSON (recommended)
GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\your-service-account-key.json

# Option 2: Use gcloud CLI instead
# Run: gcloud auth application-default login

# Optional: OpenAI API key for embeddings-based semantic search
# Get from: https://platform.openai.com/api-keys
# OPENAI_API_KEY=sk-...
    • Get your project ID from Firebase Console → Project Settings → General
    • Get service account key from Firebase Console → Project Settings → Service Accounts
    • Optional: Add OpenAI API key for semantic search (see EMBEDDINGS.md)

  3. Build:

    npm run build

Usage

Seed Firestore

Seed data from local JSON files:

# Seed all apps
npm run seed

# Seed specific app
npm run seed figma

Service Functions

The service functions are available for use as MCP tools or HTTP endpoints:

Task & Documentation Services:

  • searchTasks(appId, goalText, limit?) - Search tasks by goal text
  • getTask(taskId) - Get a task with all its steps
  • searchDocs(appId, queryText, limit?) - Search documentation sections (uses embeddings if available)
  • getUIScreen(appId, slug) - Get a UI screen with all its elements

Storage Services:

  • uploadFile(path, fileBuffer, metadata?) - Upload any file to Firebase Storage
  • uploadScreenshot(appId, screenshotBuffer, userId?, metadata?) - Upload a screenshot
  • getSignedUrl(path, expiresIn?) - Get a signed URL for private files
  • downloadFile(path) - Download a file from storage
  • deleteFile(path) - Delete a file from storage
  • listFiles(prefix, maxResults?) - List files in a directory

Example:

import { searchTasks, getTask, uploadScreenshot } from "./src/index.js";

// Search for tasks
const results = await searchTasks("figma", "create a frame");
console.log(results);

// Get full task details
const task = await getTask("task-doc-id");
console.log(task);

// Upload a screenshot
const screenshotBuffer = Buffer.from(/* screenshot data */);
const url = await uploadScreenshot("figma", screenshotBuffer, "user123");
console.log("Screenshot URL:", url);

Data Model

Firestore Collections

  • apps - App metadata
  • tasks - High-level learning flows
  • taskSteps - Step-by-step instructions
  • uiScreens - UI screen definitions
  • uiElements - UI element definitions
  • docSections - Chunked documentation

See src/types/index.ts for full type definitions.

Firebase Storage

Files are organized by path structure:

  • screenshots/{appId}/{userId}/{timestamp}.png - User screenshots
  • documents/{appId}/{filename} - App-specific documents
  • Custom paths as needed

All files can be made public or accessed via signed URLs for private access.

Development

  • Type check: npm run type-check
  • Build: npm run build
  • Dev mode: npm run dev (watch mode with tsx)

API Server

The backend includes a REST API server for easy integration with applications.

Start the Server

Development:

npm run dev:server

Production:

npm run build
npm start

The server runs on http://localhost:3000 by default (set PORT env var to change).

API Endpoints

  • GET /health - Health check
  • GET /api/apps - List all apps
  • GET /api/apps/:appId/tasks - List tasks for an app
  • GET /api/tasks/search?appId=figma&goalText=create frame - Search tasks
  • GET /api/docs/search?appId=figma&query=export - Search documentation (semantic search)
  • GET /api/apps/:appId/screens - List UI screens
  • POST /api/storage/screenshots?appId=figma - Upload screenshots

See API Documentation for complete endpoint reference.

Example Usage

// Search for tasks
const response = await fetch('http://localhost:3000/api/tasks/search?appId=figma&goalText=create frame');
const tasks = await response.json();

// Search documentation with semantic search (uses embeddings automatically)
const docs = await fetch('http://localhost:3000/api/docs/search?appId=figma&query=how to export').then(r => r.json());

📚 Want to connect embeddings to your app? See Connecting Embeddings Guide for detailed examples and integration instructions.

📦 Want to access Firebase Storage directly from your app? See Client Storage Access Guide for direct client-side access setup.

MCP Server

The backend includes an MCP (Model Context Protocol) server for AI assistants like Claude, Cursor, and VS Code.

Quick Start

  1. Build the server:

    npm run build

  2. Configure your MCP client (see MCP Setup Guide)

  3. Start using it! Ask your AI assistant questions about Figma, and it will automatically query the knowledge base.

Available MCP Tools

  • list_apps - List all apps
  • search_tasks - Search for tasks by goal
  • get_task_with_steps - Get step-by-step instructions
  • search_docs - Semantic search documentation
  • list_ui_screens_for_app - List UI screens
  • get_ui_screen_with_elements - Get screen details

See MCP Setup Guide for detailed configuration instructions.

Future Work

  • Additional apps (VS Code, Notion, etc.)
  • Authentication/authorization for API endpoints
  • MCP resources for exposing data as resources

相关 MCP