@code-context-engine/mcp 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @code-context-engine/mcp
+
+Remote MCP server for [Context Engine](https://codesay.ai). Exposes a single tool, `codebase_context`, for Claude Code, Cursor, Windsurf, and any MCP client.
+
+It syncs your local repo incrementally to the remote Context Engine, runs hybrid retrieval (semantic + keyword + symbol graph), and returns a token-budgeted context pack.
+
+## Quick start
+
+1. Sign in at [codesay.ai](https://codesay.ai) with GitHub and copy your `cek_…` API key from the console.
+2. Add this to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "context-engine": {
+      "command": "npx",
+      "args": ["-y", "@code-context-engine/mcp"],
+      "env": {
+        "CONTEXT_ENGINE_REMOTE_API_KEY": "<your cek_ key>"
+      }
+    }
+  }
+}
+```
+
+The remote service URL defaults to `https://api.codesay.ai`. Override with `CONTEXT_ENGINE_REMOTE_URL` for self-hosted deployments.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CONTEXT_ENGINE_REMOTE_API_KEY` | yes | — | User API key (`cek_…`) from the web console |
+| `CONTEXT_ENGINE_REMOTE_URL` | no | `https://api.codesay.ai` | Remote HTTP service base URL |
+| `CONTEXT_ENGINE_REMOTE_MAX_FILE_BYTES` | no | `1048576` | Skip local files larger than this when syncing |
+
+## Tool: `codebase_context`
+
+Required arguments:
+
+- `path` — absolute path to the local repository root
+- `query` — natural language or symbol-oriented search query
+
+Optional: `token_budget`, `mode` (`hybrid` / `semantic` / `keyword`), `ext_filter`, `path_prefix`, `max_files`, `feedback`.
+
+Only retrieval calls that return a context pack count against your billing quota. File sync, indexing, and feedback do not.
+
+## Programmatic use
+
+```ts
+import { createRemoteMcpServer, runCodebaseContext } from '@code-context-engine/mcp';
+```
+
+## License
+
+MIT

package/dist/codebaseContext.d.ts

@@ -0,0 +1,96 @@
+import type { MatchSource } from '@code-context-engine/shared';
+export interface CodebaseContextInput {
+    baseUrl: string;
+    apiKey: string;
+    path: string;
+    query: string;
+    tokenBudget?: number;
+    mode?: 'hybrid' | 'semantic' | 'keyword';
+    extFilter?: string[];
+    pathPrefix?: string[];
+    maxFiles?: number;
+    ignoreGlobs?: string[];
+    forceIndex?: boolean;
+    /** 本地文件发现的单文件大小上限(字节),应与远程服务的 CONTEXT_ENGINE_REMOTE_MAX_FILE_BYTES 一致——
+     * 否则本地判断"该传"的文件会在上传时被服务端按 413 拒绝。 */
+    maxFileBytes?: number;
+    feedback?: CodebaseContextFeedbackInput;
+}
+export interface CodebaseContextFeedbackInput {
+    rating: 'good' | 'bad' | 'partial';
+    expectedFiles?: string[];
+    selectedFiles?: string[];
+    missingFiles?: string[];
+    note?: string;
+    requestId?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+export declare class CodebaseContextInputError extends Error {
+    constructor(message: string);
+}
+export type CodebaseContextMatchType = MatchSource;
+export type CodebaseContextIndexStatus = 'ready' | 'indexing' | 'error';
+export interface CodebaseContextSpan {
+    start: number;
+    end: number;
+    symbols: string[];
+    code: string;
+    /** true = 索引后文件已改动且无法重定位:code 为索引时快照,行号仅作大致定位参考。 */
+    stale?: boolean;
+}
+export interface CodebaseContextOutlineEntry {
+    kind: string;
+    name: string;
+    line: number;
+}
+export type CodebaseContextConfidence = 'high' | 'medium' | 'low';
+export interface CodebaseContextResult {
+    file: string;
+    language: string;
+    /** 相对置信度分级(相对本次检索 top1)。刻意不透出内部 raw score:
+     * 量纲无意义、跨查询不可比,agent 无法正确消费浮点分,分级才是稳定契约。 */
+    confidence: CodebaseContextConfidence;
+    matchType: CodebaseContextMatchType;
+    spans: CodebaseContextSpan[];
+    outline?: CodebaseContextOutlineEntry[];
+}
+export interface CodebaseContextOutput {
+    tool: 'codebase_context';
+    query: string;
+    context: {
+        indexStatus: CodebaseContextIndexStatus;
+        query?: string;
+        mode?: 'hybrid' | 'semantic' | 'keyword';
+        tokensUsed?: number;
+        tokenBudget?: number;
+        truncated?: boolean;
+        results?: CodebaseContextResult[];
+        related?: {
+            likely_edit_targets: string[];
+            verification_targets: string[];
+        };
+    };
+    feedback: {
+        requestId: string;
+        submitted?: {
+            rating: 'good' | 'bad' | 'partial';
+        };
+    };
+}
+interface RemoteContextResponse {
+    state?: string;
+    path?: string;
+    processedFiles?: number;
+    totalFiles?: number;
+    query?: string;
+    mode?: 'hybrid' | 'semantic' | 'keyword';
+    tokensUsed?: number;
+    tokenBudget?: number;
+    truncated?: boolean;
+    results?: unknown;
+    related?: unknown;
+}
+export declare function runCodebaseContext(input: CodebaseContextInput): Promise<CodebaseContextOutput>;
+export declare function normalizeContext(context: RemoteContextResponse): CodebaseContextOutput['context'];
+export {};
+//# sourceMappingURL=codebaseContext.d.ts.map

package/dist/codebaseContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebaseContext.d.ts","sourceRoot":"","sources":["../src/codebaseContext.ts"],"names":[],"mappings":"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"}

package/dist/codebaseContext.js

@@ -0,0 +1,206 @@
+import { randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { RemoteApiClient } from './remoteClient.js';
+import { syncLocalRepo } from './syncLocalRepo.js';
+export class CodebaseContextInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CodebaseContextInputError';
+    }
+}
+const INTERNAL_CONTEXT_KEYS = new Set([
+    'activeTrainingModel',
+    'active_training_model',
+    'repoId',
+    'repo_id',
+    'trainingDataset',
+    'trainingDatasets',
+    'trainingJob',
+    'trainingJobs',
+    'trainingModel',
+    'trainingModels',
+    'training_dataset',
+    'training_datasets',
+    'training_job',
+    'training_jobs',
+    'training_model',
+    'training_models',
+    'workspaceId',
+    'workspace_id',
+]);
+export async function runCodebaseContext(input) {
+    if (!isAbsolute(input.path)) {
+        throw new CodebaseContextInputError('Use an absolute local repository path.');
+    }
+    const client = new RemoteApiClient({ baseUrl: input.baseUrl, apiKey: input.apiKey });
+    const sync = await syncLocalRepo(client, input.path, {
+        ignoreGlobs: input.ignoreGlobs,
+        forceIndex: input.forceIndex,
+        maxFileBytes: input.maxFileBytes,
+    });
+    const context = await client.context(sync.repoId, {
+        query: input.query,
+        mode: input.mode,
+        tokenBudget: input.tokenBudget,
+        maxFiles: input.maxFiles,
+        extFilter: input.extFilter,
+        pathPrefix: input.pathPrefix,
+    });
+    const requestId = input.feedback?.requestId ?? `ctx_${randomUUID().replace(/-/g, '')}`;
+    const submittedFeedback = input.feedback
+        ? await client.submitFeedback(sync.repoId, {
+            query: input.query,
+            rating: input.feedback.rating,
+            expectedFiles: input.feedback.expectedFiles,
+            selectedFiles: input.feedback.selectedFiles,
+            missingFiles: input.feedback.missingFiles,
+            note: input.feedback.note,
+            requestId,
+            metadata: input.feedback.metadata,
+        })
+        : null;
+    return {
+        tool: 'codebase_context',
+        query: input.query,
+        context: normalizeContext(context),
+        feedback: {
+            requestId,
+            submitted: submittedFeedback ? {
+                rating: submittedFeedback.rating,
+            } : undefined,
+        },
+    };
+}
+export function normalizeContext(context) {
+    if ('state' in context) {
+        return {
+            indexStatus: normalizeIndexStatus(context.state),
+        };
+    }
+    return {
+        indexStatus: 'ready',
+        query: context.query,
+        mode: context.mode,
+        tokensUsed: context.tokensUsed,
+        tokenBudget: context.tokenBudget,
+        truncated: context.truncated,
+        results: normalizeResults(context.results),
+        related: normalizeRelated(context.related),
+    };
+}
+function normalizeIndexStatus(state) {
+    if (state === 'done')
+        return 'ready';
+    if (state === 'error')
+        return 'error';
+    return 'indexing';
+}
+function normalizeResults(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .map((item) => normalizeResult(item))
+        .filter((item) => item !== null);
+}
+function confidenceValue(value) {
+    return value === 'high' || value === 'medium' || value === 'low' ? value : null;
+}
+function normalizeResult(value) {
+    if (!isRecord(value))
+        return null;
+    const file = stringValue(value.file);
+    const matchType = matchTypeValue(value.matchType);
+    if (!file || !matchType)
+        return null;
+    // 旧版 server 无 confidence 字段:按位次已隐含排序,缺省归 medium(不因版本偏差丢结果)
+    const confidence = confidenceValue(value.confidence) ?? 'medium';
+    const outline = normalizeOutline(value.outline);
+    return {
+        file,
+        language: stringValue(value.language) ?? 'unknown',
+        confidence,
+        matchType,
+        spans: normalizeSpans(value.spans),
+        ...(outline ? { outline } : {}),
+    };
+}
+function normalizeOutline(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const entries = value
+        .map((item) => {
+        if (!isRecord(item))
+            return null;
+        const kind = stringValue(item.kind);
+        const name = stringValue(item.name);
+        const line = numberValue(item.line);
+        if (!kind || !name || line === undefined)
+            return null;
+        return { kind, name, line };
+    })
+        .filter((item) => item !== null);
+    return entries.length > 0 ? entries : undefined;
+}
+function normalizeSpans(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => normalizeSpan(item))
+        .filter((item) => item !== null);
+}
+function normalizeSpan(value) {
+    if (!isRecord(value))
+        return null;
+    const start = numberValue(value.start);
+    const end = numberValue(value.end);
+    const code = stringValue(value.code);
+    if (start === undefined || end === undefined || code === undefined)
+        return null;
+    return {
+        start,
+        end,
+        symbols: stringArray(value.symbols),
+        code,
+        ...(value.stale === true ? { stale: true } : {}),
+    };
+}
+function normalizeRelated(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const related = sanitizeInternalContextFields(value);
+    return {
+        likely_edit_targets: stringArray(related.likely_edit_targets),
+        verification_targets: stringArray(related.verification_targets),
+    };
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function matchTypeValue(value) {
+    return value === 'dense' || value === 'sparse' || value === 'both' || value === 'graph' || value === 'symbol'
+        ? value
+        : undefined;
+}
+function sanitizeInternalContextFields(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeInternalContextFields(item));
+    }
+    if (!value || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (INTERNAL_CONTEXT_KEYS.has(key))
+            continue;
+        out[key] = sanitizeInternalContextFields(child);
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createRemoteMcpServer, REMOTE_MCP_PUBLIC_TOOLS } from './remoteMcpServer.js';
+export { runCodebaseContext, normalizeContext, CodebaseContextInputError, } from './codebaseContext.js';
+export { RemoteApiClient, RemoteApiError, remoteQuotaErrorMessage, type ResolvedRemoteRepo } from './remoteClient.js';
+export { syncLocalRepo, assertLocalRepoDirectory, repoKeyForPath, uploadBatchesParallel, SyncLocalRepoInputError, RemoteIndexError, } from './syncLocalRepo.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,uBAAuB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACtH,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createRemoteMcpServer, REMOTE_MCP_PUBLIC_TOOLS } from './remoteMcpServer.js';
+export { runCodebaseContext, normalizeContext, CodebaseContextInputError, } from './codebaseContext.js';
+export { RemoteApiClient, RemoteApiError, remoteQuotaErrorMessage } from './remoteClient.js';
+export { syncLocalRepo, assertLocalRepoDirectory, repoKeyForPath, uploadBatchesParallel, SyncLocalRepoInputError, RemoteIndexError, } from './syncLocalRepo.js';

package/dist/remoteClient.d.ts

@@ -0,0 +1,167 @@
+import type { ActiveTrainingModel, ApprovedTrainingModel, EvalReport, FeedbackFailurePackage, FeedbackQualitySummary, FeedbackTrainingDatasetInfo, FeedbackTrainingExample, FileManifestEntry, ManifestDiff, QueryLabel, TrainingJob, TrainingJobType, TrainingJobUpdateStatus, UploadedFile } from '@code-context-engine/shared';
+export interface RemoteApiClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** 单次请求超时(毫秒)。远程服务网络黑洞(不返回 RST)时 fetch 本身不会超时,
+     * 没有这个兜底 codebase_context 工具调用会永久挂起。默认 30s。 */
+    timeoutMs?: number;
+}
+export declare class RemoteApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+/**
+ * 供所有客户端(mcp-client 的 remoteMcpServer、server 包的 CLI)复用的 402 文案分派,
+ * 避免每个消费方各自维护一份错误码→文案映射。每次调用扣次的检索余额(quota_exhausted)
+ * 按月重置,引导"等重置";建仓/存储/上传/重建索引这四类是硬性上限,不会自动重置,
+ * 得引导"清理或升级"而不是"等重置"。无匹配码(含未来 server 新增的、或老版本纯
+ * quota_exhausted)回落到旧文案,保证向后兼容。
+ */
+export declare function remoteQuotaErrorMessage(err: RemoteApiError): string;
+export interface CreateRemoteRepoInput {
+    name: string;
+    rootHint: string;
+    clientRepoKey: string;
+}
+export interface ResolvedRemoteRepo {
+    workspaceId: string;
+    repoId: string;
+    name: string;
+    rootHint: string;
+    clientRepoKey: string;
+}
+export interface RemoteRepoResponse {
+    workspace_id: string;
+    repo_id: string;
+    name: string;
+}
+export interface RemoteContextRequest {
+    query: string;
+    mode?: 'hybrid' | 'semantic' | 'keyword';
+    tokenBudget?: number;
+    maxFiles?: number;
+    extFilter?: string[];
+    pathPrefix?: string[];
+    /** 计费幂等键;不传则自动生成。重试同一逻辑请求时应复用同一个值。 */
+    requestId?: string;
+}
+export interface RemoteFeedbackInput {
+    query: string;
+    rating: 'good' | 'bad' | 'partial';
+    expectedFiles?: string[];
+    selectedFiles?: string[];
+    missingFiles?: string[];
+    note?: string;
+    requestId?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+export interface RemoteFeedbackEvent {
+    feedbackId: string;
+    workspaceId: string;
+    repoId: string;
+    createdAt: string;
+    query: string;
+    rating: 'good' | 'bad' | 'partial';
+    expectedFiles?: string[];
+    selectedFiles?: string[];
+    missingFiles?: string[];
+    note?: string;
+    requestId?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+}
+export interface RemoteFeedbackEvalResult {
+    workspaceId: string;
+    repoId: string;
+    reportPath: string;
+    labels: QueryLabel[];
+    off: EvalReport;
+    on: EvalReport;
+    quality: FeedbackQualitySummary;
+}
+export declare class RemoteApiClient {
+    private opts;
+    private baseUrl;
+    private timeoutMs;
+    constructor(opts: RemoteApiClientOptions);
+    createRepo(input: CreateRemoteRepoInput): Promise<{
+        workspaceId: string;
+        repoId: string;
+        name: string;
+    }>;
+    getRepoByClientRepoKey(clientRepoKey: string): Promise<{
+        workspaceId: string;
+        repoId: string;
+        name: string;
+    } | null>;
+    resolveRepoByPath(path: string): Promise<ResolvedRemoteRepo | null>;
+    diffManifest(repoId: string, files: FileManifestEntry[]): Promise<ManifestDiff>;
+    health(): Promise<{
+        status: string;
+    }>;
+    uploadFiles(repoId: string, files: UploadedFile[]): Promise<{
+        status: string;
+    }>;
+    deleteFiles(repoId: string, files: string[]): Promise<{
+        status: string;
+        deleted: number;
+    }>;
+    indexRepo(repoId: string, force?: boolean): Promise<unknown>;
+    getIndexStatus(repoId: string): Promise<unknown>;
+    context(repoId: string, input: RemoteContextRequest): Promise<any>;
+    submitFeedback(repoId: string, input: RemoteFeedbackInput): Promise<RemoteFeedbackEvent>;
+    listFeedback(repoId: string, limit?: number): Promise<RemoteFeedbackEvent[]>;
+    listFeedbackLabels(repoId: string, limit?: number): Promise<QueryLabel[]>;
+    listFeedbackTrainingExamples(repoId: string, limit?: number): Promise<FeedbackTrainingExample[]>;
+    exportFeedbackTrainingDataset(repoId: string, input?: {
+        limit?: number;
+        datasetId?: string;
+    }): Promise<{
+        datasetPath: string;
+        numExamples: number;
+    }>;
+    listFeedbackTrainingDatasets(repoId: string): Promise<FeedbackTrainingDatasetInfo[]>;
+    createTrainingJob(repoId: string, input: {
+        datasetPath: string;
+        jobType: TrainingJobType;
+        modelHint?: string;
+    }): Promise<TrainingJob>;
+    listTrainingJobs(repoId: string): Promise<TrainingJob[]>;
+    listApprovedTrainingModels(repoId: string): Promise<ApprovedTrainingModel[]>;
+    activateTrainingModel(repoId: string, jobId: string, input?: {
+        activatedBy?: string;
+    }): Promise<ActiveTrainingModel>;
+    getActiveTrainingModel(repoId: string): Promise<ActiveTrainingModel | null>;
+    listTrainingModelActivations(repoId: string): Promise<ActiveTrainingModel[]>;
+    claimTrainingJob(repoId: string, input?: {
+        workerId?: string;
+    }): Promise<TrainingJob | null>;
+    releaseStaleTrainingJobs(repoId: string, input: {
+        maxRunningMs: number;
+    }): Promise<TrainingJob[]>;
+    heartbeatTrainingJob(repoId: string, jobId: string, input?: {
+        workerId?: string;
+    }): Promise<TrainingJob>;
+    updateTrainingJobStatus(repoId: string, jobId: string, input: {
+        status: TrainingJobUpdateStatus;
+        outputModelPath?: string;
+        metrics?: Record<string, number>;
+        error?: string;
+        qualityGate?: {
+            minEvalRecallAt10?: number;
+        };
+        workerId?: string;
+    }): Promise<TrainingJob>;
+    runFeedbackEval(repoId: string, input?: {
+        limit?: number;
+        maxRecallDrop?: number;
+    }): Promise<RemoteFeedbackEvalResult>;
+    getFeedbackFailures(repoId: string, input?: {
+        reportPath?: string;
+        maxItems?: number;
+        minRecallAt10?: number;
+    }): Promise<FeedbackFailurePackage>;
+    private request;
+    private get;
+}
+//# sourceMappingURL=remoteClient.d.ts.map

package/dist/remoteClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteClient.d.ts","sourceRoot":"","sources":["../src/remoteClient.ts"],"names":[],"mappings":"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"}

package/dist/remoteClient.js

@@ -0,0 +1,334 @@
+import { randomUUID } from 'node:crypto';
+export class RemoteApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Remote API ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'RemoteApiError';
+    }
+}
+const QUOTA_EXCEEDED_MESSAGES = {
+    repo_quota_exceeded: 'Remote Context Engine request failed: repo_quota_exceeded. '
+        + 'The workspace has reached its repository limit. Delete an unused repository or upgrade the subscription, then retry.',
+    storage_quota_exceeded: 'Remote Context Engine request failed: storage_quota_exceeded. '
+        + 'The workspace has reached its storage limit. Delete unused files or repositories, or upgrade the subscription, then retry.',
+    upload_quota_exceeded: 'Remote Context Engine request failed: upload_quota_exceeded. '
+        + 'The workspace has reached today\'s upload limit. Retry after the daily reset or upgrade the subscription.',
+    index_quota_exceeded: 'Remote Context Engine request failed: index_quota_exceeded. '
+        + 'The workspace has reached today\'s force-reindex limit. Retry after the daily reset or upgrade the subscription.',
+};
+/**
+ * 供所有客户端(mcp-client 的 remoteMcpServer、server 包的 CLI)复用的 402 文案分派,
+ * 避免每个消费方各自维护一份错误码→文案映射。每次调用扣次的检索余额(quota_exhausted)
+ * 按月重置,引导"等重置";建仓/存储/上传/重建索引这四类是硬性上限,不会自动重置,
+ * 得引导"清理或升级"而不是"等重置"。无匹配码(含未来 server 新增的、或老版本纯
+ * quota_exhausted)回落到旧文案,保证向后兼容。
+ */
+export function remoteQuotaErrorMessage(err) {
+    const body = err.body;
+    const code = typeof body?.error === 'string' ? body.error : undefined;
+    if (code && QUOTA_EXCEEDED_MESSAGES[code])
+        return QUOTA_EXCEEDED_MESSAGES[code];
+    return 'Remote Context Engine request failed: quota_exhausted. '
+        + 'The workspace has no retrieval quota left for this billing period. '
+        + 'Wait for the monthly reset or upgrade the subscription in the Context Engine console.';
+}
+function mapFeedback(r) {
+    return {
+        feedbackId: r.feedback_id,
+        workspaceId: r.workspace_id,
+        repoId: r.repo_id,
+        createdAt: r.created_at,
+        query: r.query,
+        rating: r.rating,
+        expectedFiles: r.expected_files,
+        selectedFiles: r.selected_files,
+        missingFiles: r.missing_files,
+        note: r.note,
+        requestId: r.request_id,
+        metadata: r.metadata,
+    };
+}
+function mapFeedbackEval(r) {
+    return {
+        workspaceId: r.workspace_id,
+        repoId: r.repo_id,
+        reportPath: r.report_path,
+        labels: r.labels,
+        off: r.off,
+        on: r.on,
+        quality: r.quality,
+    };
+}
+function mapTrainingJob(r) {
+    return {
+        jobId: r.job_id,
+        workspaceId: r.workspace_id,
+        repoId: r.repo_id,
+        datasetPath: r.dataset_path,
+        jobType: r.job_type,
+        status: r.status,
+        modelHint: r.model_hint,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+        startedAt: r.started_at,
+        finishedAt: r.finished_at,
+        outputModelPath: r.output_model_path,
+        metrics: r.metrics,
+        error: r.error,
+        claimedBy: r.claimed_by,
+        attempts: r.attempts,
+        lastHeartbeatAt: r.last_heartbeat_at,
+        quality: r.quality,
+    };
+}
+function mapApprovedTrainingModel(r) {
+    return {
+        jobId: r.job_id,
+        workspaceId: r.workspace_id,
+        repoId: r.repo_id,
+        datasetPath: r.dataset_path,
+        jobType: r.job_type,
+        modelPath: r.model_path,
+        modelHint: r.model_hint,
+        metrics: r.metrics,
+        quality: r.quality,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+        finishedAt: r.finished_at,
+    };
+}
+function mapActiveTrainingModel(r) {
+    return {
+        ...mapApprovedTrainingModel(r),
+        activatedAt: r.activated_at,
+        activatedBy: r.activated_by,
+    };
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class RemoteApiClient {
+    opts;
+    baseUrl;
+    timeoutMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    createRepo(input) {
+        return this.request('/v1/repos', {
+            name: input.name,
+            root_hint: input.rootHint,
+            client_repo_key: input.clientRepoKey,
+        }).then((r) => ({ workspaceId: r.workspace_id, repoId: r.repo_id, name: r.name }));
+    }
+    async getRepoByClientRepoKey(clientRepoKey) {
+        try {
+            const r = await this.get(`/v1/repos/by-client-key?client_repo_key=${encodeURIComponent(clientRepoKey)}`);
+            return { workspaceId: r.workspace_id, repoId: r.repo_id, name: r.name };
+        }
+        catch (err) {
+            if (err instanceof RemoteApiError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    async resolveRepoByPath(path) {
+        try {
+            const r = await this.get(`/v1/repos/resolve?path=${encodeURIComponent(path)}`);
+            return {
+                workspaceId: r.workspace_id,
+                repoId: r.repo_id,
+                name: r.name,
+                rootHint: r.root_hint,
+                clientRepoKey: r.client_repo_key,
+            };
+        }
+        catch (err) {
+            if (err instanceof RemoteApiError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    diffManifest(repoId, files) {
+        return this.request(`/v1/repos/${repoId}/manifest`, { files });
+    }
+    health() {
+        return this.get('/v1/health');
+    }
+    uploadFiles(repoId, files) {
+        return this.request(`/v1/repos/${repoId}/files:batch`, { files });
+    }
+    deleteFiles(repoId, files) {
+        return this.request(`/v1/repos/${repoId}/files:delete`, { files });
+    }
+    indexRepo(repoId, force = false) {
+        return this.request(`/v1/repos/${repoId}/index`, { force });
+    }
+    getIndexStatus(repoId) {
+        return this.get(`/v1/repos/${repoId}/index/status`);
+    }
+    async context(repoId, input) {
+        const path = `/v1/repos/${repoId}/context`;
+        const payload = {
+            query: input.query,
+            mode: input.mode,
+            token_budget: input.tokenBudget,
+            max_files: input.maxFiles,
+            ext_filter: input.extFilter,
+            path_prefix: input.pathPrefix,
+            // 计费幂等键:每次逻辑调用一个,重放/重试携带同一个则服务端不重复扣次
+            request_id: input.requestId ?? `ctxreq_${randomUUID()}`,
+        };
+        try {
+            return await this.request(path, payload);
+        }
+        catch (err) {
+            // 版本偏差兜底:升级后的 client 指向未升级的旧 server 时,旧 server 的 ContextSchema
+            // 是 .strict() 且没有 request_id 字段,会以 400 拒绝这个未知键。去掉该字段重试一次——
+            // 牺牲本次的计费幂等(旧 server 本就不支持),换取新 client 对旧 server 的可用性。
+            if (err instanceof RemoteApiError && err.status === 400
+                && JSON.stringify(err.body ?? '').includes('request_id')) {
+                const { request_id: _omit, ...legacy } = payload;
+                return await this.request(path, legacy);
+            }
+            throw err;
+        }
+    }
+    submitFeedback(repoId, input) {
+        return this.request(`/v1/repos/${repoId}/feedback`, {
+            query: input.query,
+            rating: input.rating,
+            expected_files: input.expectedFiles,
+            selected_files: input.selectedFiles,
+            missing_files: input.missingFiles,
+            note: input.note,
+            request_id: input.requestId,
+            metadata: input.metadata,
+        }).then(mapFeedback);
+    }
+    async listFeedback(repoId, limit = 100) {
+        const data = await this.get(`/v1/repos/${repoId}/feedback?limit=${encodeURIComponent(String(limit))}`);
+        return data.events.map(mapFeedback);
+    }
+    async listFeedbackLabels(repoId, limit = 100) {
+        const data = await this.get(`/v1/repos/${repoId}/feedback/labels?limit=${encodeURIComponent(String(limit))}`);
+        return data.labels;
+    }
+    async listFeedbackTrainingExamples(repoId, limit = 100) {
+        const data = await this.get(`/v1/repos/${repoId}/feedback/training?limit=${encodeURIComponent(String(limit))}`);
+        return data.examples;
+    }
+    exportFeedbackTrainingDataset(repoId, input = {}) {
+        return this.request(`/v1/repos/${repoId}/feedback/training/export`, {
+            limit: input.limit,
+            dataset_id: input.datasetId,
+        }).then((r) => ({ datasetPath: r.dataset_path, numExamples: r.num_examples }));
+    }
+    async listFeedbackTrainingDatasets(repoId) {
+        const data = await this.get(`/v1/repos/${repoId}/feedback/training/datasets`);
+        return data.datasets;
+    }
+    createTrainingJob(repoId, input) {
+        return this.request(`/v1/repos/${repoId}/training/jobs`, {
+            dataset_path: input.datasetPath,
+            job_type: input.jobType,
+            model_hint: input.modelHint,
+        }).then(mapTrainingJob);
+    }
+    async listTrainingJobs(repoId) {
+        const data = await this.get(`/v1/repos/${repoId}/training/jobs`);
+        return data.jobs.map(mapTrainingJob);
+    }
+    async listApprovedTrainingModels(repoId) {
+        const data = await this.get(`/v1/repos/${repoId}/training/models/approved`);
+        return data.models.map(mapApprovedTrainingModel);
+    }
+    activateTrainingModel(repoId, jobId, input = {}) {
+        return this.request(`/v1/repos/${repoId}/training/models/${jobId}/activate`, {
+            activated_by: input.activatedBy,
+        }).then(mapActiveTrainingModel);
+    }
+    async getActiveTrainingModel(repoId) {
+        const data = await this.get(`/v1/repos/${repoId}/training/models/active`);
+        return data.model ? mapActiveTrainingModel(data.model) : null;
+    }
+    async listTrainingModelActivations(repoId) {
+        const data = await this.get(`/v1/repos/${repoId}/training/models/activations`);
+        return data.activations.map(mapActiveTrainingModel);
+    }
+    claimTrainingJob(repoId, input = {}) {
+        return this.request(`/v1/repos/${repoId}/training/jobs:claim`, {
+            worker_id: input.workerId,
+        }).then((r) => (r.job ? mapTrainingJob(r.job) : null));
+    }
+    releaseStaleTrainingJobs(repoId, input) {
+        return this.request(`/v1/repos/${repoId}/training/jobs:release-stale`, {
+            max_running_ms: input.maxRunningMs,
+        }).then((r) => r.jobs.map(mapTrainingJob));
+    }
+    heartbeatTrainingJob(repoId, jobId, input = {}) {
+        return this.request(`/v1/repos/${repoId}/training/jobs/${jobId}/heartbeat`, {
+            worker_id: input.workerId,
+        }).then(mapTrainingJob);
+    }
+    updateTrainingJobStatus(repoId, jobId, input) {
+        return this.request(`/v1/repos/${repoId}/training/jobs/${jobId}/status`, {
+            status: input.status,
+            output_model_path: input.outputModelPath,
+            metrics: input.metrics,
+            error: input.error,
+            worker_id: input.workerId,
+            quality_gate: input.qualityGate ? {
+                min_eval_recall_at_10: input.qualityGate.minEvalRecallAt10,
+            } : undefined,
+        }).then(mapTrainingJob);
+    }
+    runFeedbackEval(repoId, input = {}) {
+        return this.request(`/v1/repos/${repoId}/eval/feedback`, {
+            limit: input.limit,
+            max_recall_drop: input.maxRecallDrop,
+        }).then(mapFeedbackEval);
+    }
+    getFeedbackFailures(repoId, input = {}) {
+        const params = new URLSearchParams();
+        if (input.reportPath)
+            params.set('report_path', input.reportPath);
+        if (input.maxItems !== undefined)
+            params.set('max_items', String(input.maxItems));
+        if (input.minRecallAt10 !== undefined)
+            params.set('min_recall_at_10', String(input.minRecallAt10));
+        const qs = params.toString();
+        return this.get(`/v1/repos/${repoId}/eval/feedback/failures${qs ? `?${qs}` : ''}`);
+    }
+    async request(path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${this.opts.apiKey}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new RemoteApiError(res.status, data);
+        return data;
+    }
+    async get(path) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'GET',
+            headers: {
+                authorization: `Bearer ${this.opts.apiKey}`,
+            },
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new RemoteApiError(res.status, data);
+        return data;
+    }
+}

package/dist/remoteMcpServer.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const REMOTE_MCP_PUBLIC_TOOLS: readonly ["codebase_context"];
+export declare function createRemoteMcpServer(): McpServer;
+//# sourceMappingURL=remoteMcpServer.d.ts.map

package/dist/remoteMcpServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteMcpServer.d.ts","sourceRoot":"","sources":["../src/remoteMcpServer.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAepE,eAAO,MAAM,uBAAuB,+BAAgC,CAAC;AAgGrE,wBAAgB,qBAAqB,cAyDpC"}

package/dist/remoteMcpServer.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadConfig, resolveRemoteUrl } from '@code-context-engine/shared';
+import { CodebaseContextInputError, runCodebaseContext } from './codebaseContext.js';
+import { RemoteApiError, remoteQuotaErrorMessage } from './remoteClient.js';
+import { SyncLocalRepoInputError } from './syncLocalRepo.js';
+const ok = (data) => ({
+    content: [{ type: 'text', text: JSON.stringify(data) }],
+    structuredContent: data,
+});
+export const REMOTE_MCP_PUBLIC_TOOLS = ['codebase_context'];
+const codebaseContextSpanSchema = z.object({
+    start: z.number(),
+    end: z.number(),
+    symbols: z.array(z.string()),
+    code: z.string(),
+    // 索引后文件已改动且无法重定位:code 为索引时快照,行号仅作大致定位参考
+    stale: z.boolean().optional(),
+}).strict();
+const codebaseContextOutlineSchema = z.object({
+    kind: z.string(),
+    name: z.string(),
+    line: z.number(),
+}).strict();
+const codebaseContextResultSchema = z.object({
+    file: z.string(),
+    language: z.string(),
+    confidence: z.enum(['high', 'medium', 'low']),
+    matchType: z.enum(['dense', 'sparse', 'both', 'graph', 'symbol']),
+    spans: z.array(codebaseContextSpanSchema),
+    outline: z.array(codebaseContextOutlineSchema).optional(),
+}).strict();
+const codebaseContextRelatedSchema = z.object({
+    likely_edit_targets: z.array(z.string()),
+    verification_targets: z.array(z.string()),
+}).strict();
+const codebaseContextIndexStatusSchema = z.enum(['ready', 'indexing', 'error']);
+const codebaseContextInputSchema = z.object({
+    path: z.string().refine((value) => isAbsolute(value), {
+        message: 'Use an absolute local repository path.',
+    }).describe('本地代码库绝对路径'),
+    query: z.string().describe('自然语言或代码意图查询。Write the query in English for best retrieval quality; CJK queries are auto-translated before search (adding latency), except in keyword mode which searches the literal text.'),
+    token_budget: z.number().int().positive().optional().describe('返回内容总 token 上限, 默认 8000'),
+    mode: z.enum(['hybrid', 'semantic', 'keyword']).optional().describe('默认 hybrid'),
+    ext_filter: z.array(z.string()).optional().describe("限定扩展名, 如 ['.py','.ts']"),
+    path_prefix: z.array(z.string()).optional().describe("限定仓库相对路径前缀, 如 ['packages/server/src']"),
+    max_files: z.number().int().positive().optional().describe('返回文件数上限, 默认 20'),
+    feedback: z.object({
+        rating: z.enum(['good', 'bad', 'partial']).describe('本次上下文结果质量反馈'),
+        request_id: z.string().optional().describe('上一次 codebase_context 返回的 feedback.requestId'),
+    }).strict().optional().describe('可选结果质量反馈; 通过同一个 codebase_context 工具写回服务端'),
+}).strict();
+const codebaseContextOutputSchema = z.object({
+    tool: z.literal('codebase_context'),
+    query: z.string(),
+    context: z.object({
+        indexStatus: codebaseContextIndexStatusSchema,
+        query: z.string().optional(),
+        mode: z.enum(['hybrid', 'semantic', 'keyword']).optional(),
+        tokensUsed: z.number().optional(),
+        tokenBudget: z.number().optional(),
+        truncated: z.boolean().optional(),
+        results: z.array(codebaseContextResultSchema).optional(),
+        related: codebaseContextRelatedSchema.optional(),
+    }).strict(),
+    feedback: z.object({
+        requestId: z.string(),
+        submitted: z.object({
+            rating: z.enum(['good', 'bad', 'partial']),
+        }).strict().optional(),
+    }).strict(),
+}).strict();
+function publicRemoteErrorMessage(err) {
+    if (err instanceof CodebaseContextInputError || err instanceof SyncLocalRepoInputError) {
+        return `codebase_context input invalid: ${err.message}`;
+    }
+    if (err instanceof RemoteApiError) {
+        if (err.status === 401 || err.status === 403) {
+            return 'Remote Context Engine request failed: authentication_failed. Check the local MCP API key configuration.';
+        }
+        if (err.status === 402) {
+            return remoteQuotaErrorMessage(err);
+        }
+        if (err.status === 413) {
+            return 'Remote Context Engine request failed: payload_too_large. Reduce ignored files or split the repository, then retry.';
+        }
+        if (err.status === 400) {
+            return 'Remote Context Engine request failed: invalid_request. Check the local MCP input and repository sync settings.';
+        }
+        if (err.status >= 500) {
+            return 'Remote Context Engine request failed: server_error. Try again or contact the server operator.';
+        }
+    }
+    return 'Remote Context Engine request failed: unavailable. Check the remote service and network, then retry.';
+}
+export function createRemoteMcpServer() {
+    const cfg = loadConfig();
+    const server = new McpServer({ name: 'context-engine-remote', version: '0.1.0' });
+    server.registerTool(REMOTE_MCP_PUBLIC_TOOLS[0], {
+        description: '同步本地代码库到远程 Context Engine, 并返回按文件聚合、带 token 预算的上下文包。用于需要理解代码位置、调用关系或修改目标的查询。',
+        inputSchema: codebaseContextInputSchema,
+        outputSchema: codebaseContextOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ path, query, token_budget, mode, ext_filter, path_prefix, max_files, feedback, }) => {
+        const baseUrl = resolveRemoteUrl();
+        const key = cfg.remote.apiKey;
+        if (!key)
+            throw new Error('Remote Context Engine is not configured. Contact the server operator.');
+        try {
+            const out = await runCodebaseContext({
+                baseUrl,
+                apiKey: key,
+                path,
+                query,
+                tokenBudget: token_budget,
+                mode,
+                extFilter: ext_filter,
+                pathPrefix: path_prefix,
+                maxFiles: max_files,
+                maxFileBytes: cfg.remote.maxFileBytes,
+                feedback: feedback ? {
+                    rating: feedback.rating,
+                    requestId: feedback.request_id,
+                } : undefined,
+            });
+            return ok(out);
+        }
+        catch (err) {
+            throw new Error(publicRemoteErrorMessage(err));
+        }
+    });
+    return server;
+}
+async function main() {
+    await createRemoteMcpServer().connect(new StdioServerTransport());
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/syncLocalRepo.d.ts

@@ -0,0 +1,37 @@
+import { type UploadedFile } from '@code-context-engine/shared';
+import type { RemoteApiClient } from './remoteClient.js';
+export interface SyncLocalRepoOptions {
+    ignoreGlobs?: string[];
+    forceIndex?: boolean;
+    clientRepoKey?: string;
+    name?: string;
+    /** 应与远程服务的单文件大小上限一致,否则本地认为"该传"的文件会被服务端按 413 拒绝。 */
+    maxFileBytes?: number;
+    /** 等待远程索引完成的时间上限;超时不报错,带进行中状态返回。 */
+    waitForIndexMs?: number;
+}
+export interface SyncLocalRepoResult {
+    workspaceId: string;
+    repoId: string;
+    totalFiles: number;
+    uploaded: number;
+    deleted: number;
+    /** 返回时的远程索引状态:'done' 可立即检索;其余表示索引仍在后台进行。 */
+    indexState: string;
+}
+export declare class RemoteIndexError extends Error {
+    constructor(message: string);
+}
+export declare class SyncLocalRepoInputError extends Error {
+    constructor(message: string);
+}
+interface SizedUpload extends UploadedFile {
+    size: number;
+}
+export declare function syncLocalRepo(client: RemoteApiClient, repoPath: string, opts?: SyncLocalRepoOptions): Promise<SyncLocalRepoResult>;
+export declare function repoKeyForPath(path: string): string;
+export declare function assertLocalRepoDirectory(path: string): void;
+/** @internal 导出供单测断言并行上传上限。 */
+export declare function uploadBatchesParallel(client: RemoteApiClient, repoId: string, batches: SizedUpload[][]): Promise<void>;
+export {};
+//# sourceMappingURL=syncLocalRepo.d.ts.map

package/dist/syncLocalRepo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncLocalRepo.d.ts","sourceRoot":"","sources":["../src/syncLocalRepo.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACvG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAWzD,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,UAAU,WAAY,SAAQ,YAAY;IACxC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAwE9B;AAuCD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAU3D;AAyBD,+BAA+B;AAC/B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EAAE,EAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/syncLocalRepo.js

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { basename, relative, resolve } from 'node:path';
+import { discoverFiles } from '@code-context-engine/shared';
+const MAX_UPLOAD_FILES_PER_BATCH = 1000;
+const MAX_DELETE_FILES_PER_BATCH = 1000;
+const MAX_UPLOAD_RAW_BYTES_PER_BATCH = 15_000_000;
+/** 并行上传 batch 数上限(仍等全部 batch 完成后再 index)。 */
+const UPLOAD_BATCH_CONCURRENCY = 4;
+const INDEX_POLL_INTERVAL_MS = 500;
+/** 低于 RemoteApiClient 单请求 30s 超时;冷启动大仓库等不完就带"索引中"状态返回,由 /context 的 IndexPending 信封接力。 */
+const DEFAULT_WAIT_FOR_INDEX_MS = 20_000;
+export class RemoteIndexError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RemoteIndexError';
+    }
+}
+export class SyncLocalRepoInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SyncLocalRepoInputError';
+    }
+}
+export async function syncLocalRepo(client, repoPath, opts = {}) {
+    let root = resolve(repoPath);
+    assertLocalRepoDirectory(root);
+    let repo;
+    const resolved = opts.clientRepoKey ? null : await resolveExistingRepo(client, root);
+    if (resolved) {
+        root = resolve(resolved.rootHint);
+        repo = resolved;
+    }
+    else {
+        repo = await client.createRepo({
+            name: opts.name ?? basename(root),
+            rootHint: root,
+            clientRepoKey: opts.clientRepoKey ?? repoKeyForPath(root),
+        });
+    }
+    const { files } = await discoverFiles(root, opts.ignoreGlobs, opts.maxFileBytes);
+    const manifest = files.map((full) => {
+        const content = readFileSync(full);
+        return {
+            path: relative(root, full).replace(/\\/g, '/'),
+            sha256: sha256(content),
+            size: content.length,
+        };
+    });
+    const diff = await client.diffManifest(repo.repoId, manifest);
+    const uploadSet = new Set([...diff.missing, ...diff.changed]);
+    const uploads = manifest
+        .filter((f) => uploadSet.has(f.path))
+        .map((f) => ({
+        path: f.path,
+        sha256: f.sha256,
+        size: f.size,
+        contentBase64: readFileSync(resolve(root, f.path)).toString('base64'),
+    }));
+    for (const batch of chunkItems(diff.deleted, MAX_DELETE_FILES_PER_BATCH)) {
+        await client.deleteFiles(repo.repoId, batch);
+    }
+    await uploadBatchesParallel(client, repo.repoId, chunkUploads(uploads));
+    // force 仅在调用方显式要求时使用:普通变更走服务端 contentHash 增量(只重嵌变更文件),
+    // 隐式 force 会导致"改一个文件 → 整仓重新 embedding"的成本放大(曾是 P0 级产品缺陷)。
+    const changed = uploads.length > 0 || diff.deleted.length > 0;
+    let indexState = 'idle';
+    let needStart = !!opts.forceIndex || changed;
+    if (!needStart) {
+        // 无变更时先看状态:'done' 直接跳过 /index(免掉每次调用的增量扫描税);
+        // 'idle' 含服务端重启丢内存状态的情况——磁盘索引若在,增量索引秒级空跑,必须触发以自愈
+        indexState = (await fetchIndexStatus(client, repo.repoId)).state;
+        needStart = indexState === 'idle' || indexState === 'error';
+    }
+    if (needStart) {
+        await client.indexRepo(repo.repoId, opts.forceIndex ?? false);
+    }
+    if (needStart || !isSettledIndexState(indexState)) {
+        const settled = await waitForIndexSettled(client, repo.repoId, opts.waitForIndexMs ?? DEFAULT_WAIT_FOR_INDEX_MS);
+        indexState = settled.state;
+        if (indexState === 'error') {
+            throw new RemoteIndexError(`Remote indexing failed: ${settled.error ?? 'unknown error'}`);
+        }
+    }
+    return {
+        workspaceId: repo.workspaceId,
+        repoId: repo.repoId,
+        totalFiles: manifest.length,
+        uploaded: uploads.length,
+        deleted: diff.deleted.length,
+        indexState,
+    };
+}
+function isSettledIndexState(state) {
+    return state === 'done' || state === 'error';
+}
+async function fetchIndexStatus(client, repoId) {
+    const raw = (await client.getIndexStatus(repoId));
+    return {
+        state: typeof raw?.state === 'string' ? raw.state : 'idle',
+        error: typeof raw?.error === 'string' ? raw.error : null,
+    };
+}
+/** 轮询远程索引状态直到进入稳态(done/error)或预算耗尽;超时按当前进行中状态返回,不视为失败。 */
+async function waitForIndexSettled(client, repoId, budgetMs) {
+    const deadline = Date.now() + budgetMs;
+    for (;;) {
+        const status = await fetchIndexStatus(client, repoId);
+        if (isSettledIndexState(status.state))
+            return status;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return status;
+        await sleep(Math.min(INDEX_POLL_INTERVAL_MS, remaining));
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function repoKeyForPath(path) {
+    return `local_${sha256(Buffer.from(path)).slice(0, 24)}`;
+}
+export function assertLocalRepoDirectory(path) {
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        throw new SyncLocalRepoInputError('Local repository path must exist and be a directory.');
+    }
+    if (!stat.isDirectory()) {
+        throw new SyncLocalRepoInputError('Local repository path must exist and be a directory.');
+    }
+}
+function chunkUploads(files) {
+    const batches = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const file of files) {
+        if (current.length > 0
+            && (current.length >= MAX_UPLOAD_FILES_PER_BATCH
+                || currentBytes + file.size > MAX_UPLOAD_RAW_BYTES_PER_BATCH)) {
+            batches.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+        current.push(file);
+        currentBytes += file.size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+/** @internal 导出供单测断言并行上传上限。 */
+export async function uploadBatchesParallel(client, repoId, batches) {
+    if (batches.length === 0)
+        return;
+    let next = 0;
+    async function worker() {
+        while (next < batches.length) {
+            const idx = next++;
+            const batch = batches[idx].map(({ size: _size, ...file }) => file);
+            await client.uploadFiles(repoId, batch);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(UPLOAD_BATCH_CONCURRENCY, batches.length) }, () => worker()));
+}
+function chunkItems(items, maxItems) {
+    const batches = [];
+    for (let i = 0; i < items.length; i += maxItems) {
+        batches.push(items.slice(i, i + maxItems));
+    }
+    return batches;
+}
+async function resolveExistingRepo(client, root) {
+    const resolved = await client.resolveRepoByPath(root);
+    if (!resolved)
+        return null;
+    try {
+        // rootHint 可能来自同一 workspace 的另一台机器,本地不存在则退回新建
+        assertLocalRepoDirectory(resolved.rootHint);
+    }
+    catch {
+        return null;
+    }
+    return resolved;
+}
+function sha256(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@code-context-engine/mcp",
+  "version": "0.1.0",
+  "description": "MCP server that gives Claude Code, Cursor, and any MCP client real codebase context without burning tokens — incremental sync, hybrid dense+sparse+symbol-graph retrieval, token-budgeted context packs.",
+  "license": "MIT",
+  "homepage": "https://codesay.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yeuxuan/context-engine.git",
+    "directory": "packages/mcp-client"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepublishOnly": "tsc -b"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "cursor",
+    "codebase-context",
+    "code-search",
+    "code-rag",
+    "semantic-code-search",
+    "token-budget"
+  ],
+  "type": "module",
+  "bin": {
+    "context-engine": "./dist/remoteMcpServer.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@code-context-engine/shared": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  }
+}