语义代码搜索工具

❌ Traditional: grep -r "def authenticate" app/
✅ Semantica: "Find authentication logic"
   → Returns auth functions, middleware, login flows across all files

# 1. Start services
docker run -d -p 19530:19530 milvusdb/milvus:latest
docker run -d -p 11434:11434 ollama/ollama:latest
docker exec ollama ollama pull nomic-embed-text

# 2. Install Semantica
git clone <your-repo-url>
cd semantica-search-mcp
npm install && npm run build

# 3. Configure Claude Code
# Add to ~/.config/claude/claude_desktop_config.json (Linux)
# Or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
{
  "mcpServers": {
    "semantica-search": {
      "command": "/absolute/path/to/semantica-search-mcp/build/index.js"
    }
  }
}

# 4. Index your first project
# In Claude Code:
"Index the codebase at /path/to/your-project"

# 1. Install Semantica (same as Option 1, steps 2-3)

# 2. Set API key
export OPENAI_API_KEY="sk-..."

# 3. Create project config
# In your project: .semantica/config.json
{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536,
    "batchSize": 128,
    "concurrency": 3,
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "timeout": 30000
    }
  },
  "vectordb": {
    "provider": "milvus",
    "collectionName": "my_project"
  }
}

# 4. Index your project (same as Option 1)

{
  "version": "1.0.0",

  "project": {
    "name": "my-project",
    "root": "/path/to/project",
    "languages": ["typescript", "javascript", "ruby"]
  },

  "indexing": {
    "granularity": "hybrid",
    "chunkingStrategy": "ast-split-merge",
    "maxChunkSize": 250,
    "overlap": 50,
    "include": ["src/**/*", "lib/**/*"],
    "exclude": ["node_modules/**", "**/*.test.*"],
    "languageConfig": {
      "typescript": {
        "extensions": [".ts", ".tsx"],
        "chunkTypes": ["function", "class", "interface", "type"]
      },
      "ruby": {
        "extensions": [".rb"],
        "chunkTypes": ["def", "class", "module"]
      }
    }
  },

  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536,
    "batchSize": 128,
    "concurrency": 3,
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "timeout": 30000
    }
  },

  "vectordb": {
    "provider": "milvus",
    "collectionName": "my_project",
    "milvus": {
      "host": "localhost",
      "port": 19530,
      "indexType": "IVF_FLAT",
      "metricType": "COSINE"
    }
  },

  "search": {
    "strategy": "hybrid",
    "maxResults": 10,
    "minScore": 0.5,
    "hybrid": {
      "vectorWeight": 0.7,
      "keywordWeight": 0.3
    }
  }
}

{
  "include": ["src/**/*", "lib/**/*"], // Core code only
  "exclude": [
    "node_modules/**", // Dependencies
    "**/*.test.*", // Tests
    "**/*.spec.*", // Specs
    "dist/**", // Build output
    "coverage/**" // Test coverage
  ]
}

{
  "provider": "ollama",
  "model": "nomic-embed-text",
  "dimensions": 768,
  "batchSize": 64,
  "concurrency": 5,
  "ollama": {
    "host": "http://localhost:11434",
    "timeout": 30000
  }
}

{
  "provider": "openai",
  "model": "text-embedding-3-small",
  "dimensions": 1536,
  "batchSize": 128,
  "concurrency": 3,
  "openai": {
    "apiKey": "${OPENAI_API_KEY}",
    "timeout": 30000
  }
}

{
  "indexing": {
    "include": ["src/**/*"],
    "exclude": ["**/*.test.*"]
  },
  "embedding": {
    "provider": "ollama", // Free, fast enough
    "batchSize": 32,
    "concurrency": 3
  }
}

{
  "indexing": {
    "include": ["src/**/*", "lib/**/*"],
    "exclude": ["node_modules/**", "**/*.test.*", "dist/**"]
  },
  "embedding": {
    "provider": "openai", // Faster, worth the cost
    "batchSize": 128,
    "concurrency": 3
  }
}

{
  "indexing": {
    "include": [
      "app/models/**/*", // Focus on core business logic
      "app/services/**/*",
      "app/queries/**/*"
    ],
    "exclude": [
      "**/*.test.*",
      "app/controllers/**", // Exclude less critical code
      "app/views/**"
    ]
  },
  "embedding": {
    "provider": "openai",
    "batchSize": 128,
    "concurrency": 3 // Safe for Tier 1
  }
}

{
  "embedding": {
    "provider": "openai", // No Docker needed!
    "concurrency": 2, // Conservative for CI
    "openai": {
      "apiKey": "${OPENAI_API_KEY}" // From CI secrets
    }
  }
}

npm test

# Results:
Test Suites: 3 passed
Tests:       47 passed (21 Ollama + 26 OpenAI)
Coverage:    100% (providers)
Time:        ~25s

"Index the codebase at /Users/me/Projects/my-app"

📊 Pre-flight check for my-app
────────────────────────────────────────────────────────

📁 Scope:
   • Files to index: 2,367
   • Estimated chunks: 8,474
   • Provider: openai

⏱️  Estimated time: ~2-3 minutes
   (This is a one-time operation)

💰 Estimated cost: ~$0.0297

🔍 System checks:
   ✅ Configuration file
   ✅ Vector database connection
   ✅ Embedding provider
   ✅ Disk space

✅ Ready to index!
   Indexing will run in background - you can continue working.

────────────────────────────────────────────────────────

🚀 Indexing started in background!

Job ID: index_1707445123
Estimated time: ~2-3 minutes
Estimated cost: ~$0.0297

💡 You can continue using Claude Code normally.
   Check progress: "Get index status"
   I'll show a summary when indexing completes!

📝 This is a one-time operation. Future updates via git hooks are <10s.

"Search for authentication logic in my-app"

🔍 Found 8 results (0.7s):

1. src/services/auth.service.ts:45-67 (score: 0.92)
   export class AuthService {
     async authenticate(credentials: Credentials) {
       // JWT-based authentication
     }
   }

2. src/middleware/auth.middleware.ts:12-28 (score: 0.87)
   export function requireAuth(req, res, next) {
     // Check JWT token
   }

"Get index status for my-app"

📊 Indexing in progress (Job #index_1707445123)

Phase: Embedding
Progress: 67.3% (5,700/8,474 chunks)
Speed: 52 chunks/s
ETA: 2.1 minutes

✅ Index Status for my-app

Collection: my_app
Status: Ready
Vectors: 8,346
Dimensions: 1536
Last updated: 2 minutes ago

{ "embedding": { "provider": "openai", "concurrency": 3 } }

{ "embedding": { "concurrency": 5 } } // For Tier 2+ (5,000 RPM)

{
  "indexing": {
    "include": ["app/models/**", "app/services/**"]
  }
}

{ "embedding": { "provider": "ollama" } }

{ "embedding": { "concurrency": 3 } } // vs 5: more reliable

{
  "indexing": {
    "include": ["**/*.ts", "**/*.rb"], // Match all supported files
    "exclude": ["node_modules/**"]
  }
}

# Check if running
curl http://localhost:19530/healthz

# Start if needed
docker run -d -p 19530:19530 milvusdb/milvus:latest

# Check if running
curl http://localhost:11434/api/tags

# Start if needed
ollama serve

# Check API key is set
echo $OPENAI_API_KEY

# Set if missing
export OPENAI_API_KEY="sk-..."

{
  "embedding": {
    "concurrency": 2, // Down from 3 or 5
    "batchSize": 64 // Down from 128
  }
}

"Enable git hooks for my-project"

"Re-index changed files in my-project"

# Project 1
cd /path/to/project1
# Create .semantica/config.json with collectionName: "project1"

# Project 2
cd /path/to/project2
# Create .semantica/config.json with collectionName: "project2"

# Index both
"Index the codebase at /path/to/project1"
"Index the codebase at /path/to/project2"

# Search specific project
"Search for auth in project1"

{
  "embedding": {
    "provider": "openai",
    "dimensions": 1536 // Changed from 768!
  }
}

"Clear index for my-project"

"Index the codebase at /path/to/my-project"

git clone <repo-url>
cd semantica-search-mcp
npm install
npm run build

npm run watch          # Auto-rebuild on changes
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run inspector     # MCP debugging

{
  "openai": {
    "apiKey": "${OPENAI_API_KEY}" // ✅ Environment variable
  }
}

{
  "openai": {
    "apiKey": "sk-proj-..." // ❌ NEVER hardcode!
  }
}