Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/ServerToolHandler.ts:350-410 (handler)

  Async handler method that executes the sync_storage tool: gets git status, commits changes if any with descriptive message, attempts to push to remote if configured, handles errors.

  async syncStorageAsync(): Promise<string> {
    const context = this.createContext('sync_storage', {});
  
    try {
      // Get current status before sync
      const { stdout: beforeStatus } = await gitCommandAsync(STORAGE_PATH, 'status', '--porcelain');
      const hasChanges = beforeStatus.trim().length > 0;
  
      if (!hasChanges) {
        // No changes to sync
        const result = {
          message: 'No changes to sync - working tree clean',
          files_committed: 0,
          pushed: false,
        };
        this.logSuccess('sync_storage', result, context);
        return this.formatSuccessResponse(result);
      }
  
      // Count files to be committed
      const filesCount = beforeStatus.trim().split('\n').length;
  
      // Perform auto-commit with a descriptive message
      const timestamp = new Date().toISOString();
      const commitMessage = `Sync storage: ${filesCount} file${filesCount > 1 ? 's' : ''} updated at ${timestamp}`;
      await autoCommitAsync(STORAGE_PATH, commitMessage);
  
      // Check if push was successful
      const hasRemote = await hasGitRemoteAsync(STORAGE_PATH);
      let pushed = false;
      let pushError: string | undefined;
  
      if (hasRemote) {
        try {
          await pushToOriginAsync(STORAGE_PATH);
          pushed = true;
        } catch (error) {
          pushError = error instanceof Error ? error.message : String(error);
        }
      }
  
      const result = {
        message: `Successfully committed ${filesCount} file${filesCount > 1 ? 's' : ''}`,
        files_committed: filesCount,
        pushed,
        push_error: pushError,
        commit_message: commitMessage,
      };
  
      this.logSuccess('sync_storage', { files_committed: filesCount, pushed }, context);
      return this.formatSuccessResponse(result);
    } catch (error) {
      const mcpError = new MCPError(
        MCPErrorCode.GIT_ERROR,
        `Failed to sync storage: ${error instanceof Error ? error.message : String(error)}`,
        { traceId: context.traceId }
      );
      this.logError('sync_storage', {}, mcpError, context);
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:585-603 (registration)

  Registers the sync_storage tool on the MCP server, with empty input schema, delegating execution to serverHandler.syncStorageAsync()

  server.registerTool(
    'sync_storage',
    {
      title: 'Sync Storage',
      description: TOOL_DESCRIPTIONS.sync_storage,
      inputSchema: {},
    },
    async () => {
      const result = await serverHandler.syncStorageAsync();
      return {
        content: [
          {
            type: 'text',
            text: result,
          },
        ],
      };
    }
  );

• src/knowledge-mcp/handlers/ServerToolHandler.ts:150-210 (handler)

  Synchronous version of the sync_storage handler with identical logic to the async version.

  syncStorage(): string {
    const context = this.createContext('sync_storage', {});
  
    try {
      // Get current status before sync
      const { stdout: beforeStatus } = gitCommand(STORAGE_PATH, 'status', '--porcelain');
      const hasChanges = beforeStatus.trim().length > 0;
  
      if (!hasChanges) {
        // No changes to sync
        const result = {
          message: 'No changes to sync - working tree clean',
          files_committed: 0,
          pushed: false,
        };
        this.logSuccess('sync_storage', result, context);
        return this.formatSuccessResponse(result);
      }
  
      // Count files to be committed
      const filesCount = beforeStatus.trim().split('\n').length;
  
      // Perform auto-commit with a descriptive message
      const timestamp = new Date().toISOString();
      const commitMessage = `Sync storage: ${filesCount} file${filesCount > 1 ? 's' : ''} updated at ${timestamp}`;
      autoCommit(STORAGE_PATH, commitMessage);
  
      // Check if push was successful
      const hasRemote = hasGitRemote(STORAGE_PATH);
      let pushed = false;
      let pushError: string | undefined;
  
      if (hasRemote) {
        try {
          pushToOrigin(STORAGE_PATH);
          pushed = true;
        } catch (error) {
          pushError = error instanceof Error ? error.message : String(error);
        }
      }
  
      const result = {
        message: `Successfully committed ${filesCount} file${filesCount > 1 ? 's' : ''}`,
        files_committed: filesCount,
        pushed,
        push_error: pushError,
        commit_message: commitMessage,
      };
  
      this.logSuccess('sync_storage', { files_committed: filesCount, pushed }, context);
      return this.formatSuccessResponse(result);
    } catch (error) {
      const mcpError = new MCPError(
        MCPErrorCode.GIT_ERROR,
        `Failed to sync storage: ${error instanceof Error ? error.message : String(error)}`,
        { traceId: context.traceId }
      );
      this.logError('sync_storage', {}, mcpError, context);
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/config/toolDescriptions.ts:792-821 (schema)

  Tool description string used in the registration, providing usage guidelines and expected return format.

    sync_storage: `Force git add, commit, and push all changes in the knowledge datastore.
  
  When to use this tool:
  - Manually triggering backup to remote
  - Ensuring changes are persisted
  - Before major operations
  - Resolving sync issues
  - Explicit backup request
  
  Key features:
  - Commits ALL uncommitted changes
  - Pushes to configured remote
  - Auto-generates commit message
  - Handles push failures gracefully
  - Forces synchronization
  
  You should:
  1. Check storage_status first
  2. Use when auto-sync fails
  3. Verify remote is configured
  4. Handle push failures appropriately
  5. Use sparingly (auto-sync usually works)
  
  DO NOT use when:
  - No changes to commit
  - Remote not configured
  - Auto-sync is working fine
  
  Returns: {success: bool, message: str, files_committed: int, pushed: bool, push_error?: str, commit_message: str}`,
  };