Knowledge MCP Server

Instructions

Implementation Reference

• src/knowledge-mcp/handlers/ServerToolHandler.ts:243-345 (handler)

  The primary handler implementation getStorageStatusAsync() that performs git commands to retrieve storage status including uncommitted changes, current branch, last commit, remote status, and detailed git status output.

  async getStorageStatusAsync(): Promise<string> {
    const context = this.createContext('get_storage_status', {});
  
    try {
      // Get git status
      let statusOutput = '';
      let hasChanges = false;
      try {
        const result = await gitCommandAsync(STORAGE_PATH, 'status', '--porcelain');
        statusOutput = result.stdout.trim();
        hasChanges = statusOutput.length > 0;
      } catch {
        // Git status failed, assume no changes
        hasChanges = false;
      }
  
      // Get current branch
      let currentBranch = '';
      try {
        const result = await gitCommandAsync(STORAGE_PATH, 'branch', '--show-current');
        currentBranch = result.stdout.trim();
      } catch {
        // No branch if no commits yet
        currentBranch = '';
      }
  
      // Get last commit info
      let lastCommit = 'No commits yet';
      try {
        const { stdout: logOutput } = await gitCommandAsync(
          STORAGE_PATH,
          'log',
          '-1',
          '--pretty=format:%h - %s (%cr)'
        );
        if (logOutput.trim()) {
          lastCommit = logOutput.trim();
        }
      } catch {
        // No commits yet
      }
  
      // Check if remote exists
      const hasRemote = await hasGitRemoteAsync(STORAGE_PATH);
  
      // Get remote status if available
      let remoteStatus = 'No remote configured';
      if (hasRemote) {
        try {
          const { stdout: remoteOutput } = await gitCommandAsync(
            STORAGE_PATH,
            'remote',
            'get-url',
            'origin'
          );
          remoteStatus = `Remote: ${remoteOutput.trim()}`;
  
          // Check if we're ahead/behind
          try {
            const { stdout: revListOutput } = await gitCommandAsync(
              STORAGE_PATH,
              'rev-list',
              '--count',
              '--left-right',
              'HEAD...origin/main'
            );
            const [ahead, behind] = revListOutput
              .trim()
              .split('\t')
              .map((n) => parseInt(n, 10));
            if (ahead > 0 || behind > 0) {
              remoteStatus += ` (${ahead} ahead, ${behind} behind)`;
            }
          } catch {
            // Can't determine ahead/behind status
          }
        } catch {
          // Error getting remote URL
        }
      }
  
      const result = {
        storage_path: STORAGE_PATH,
        has_changes: hasChanges,
        current_branch: currentBranch,
        last_commit: lastCommit,
        remote_status: remoteStatus,
        uncommitted_files: statusOutput.trim() ? statusOutput.trim().split('\n').length : 0,
        status_details: statusOutput.trim() || 'Working tree clean',
      };
  
      this.logSuccess('get_storage_status', {}, context);
      return this.formatSuccessResponse(result);
    } catch (error) {
      const mcpError = new MCPError(
        MCPErrorCode.GIT_ERROR,
        `Failed to get storage status: ${error instanceof Error ? error.message : String(error)}`,
        { traceId: context.traceId }
      );
      this.logError('get_storage_status', {}, mcpError, context);
      return this.formatErrorResponse(mcpError, context);
    }
  }

• src/knowledge-mcp/server.ts:565-583 (registration)

  Registers the get_storage_status tool with the MCP server, specifying title, description from TOOL_DESCRIPTIONS, empty inputSchema, and handler delegation to serverHandler.getStorageStatusAsync().

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

• src/knowledge-mcp/config/toolDescriptions.ts:762-790 (schema)

  Detailed tool description including usage guidelines, when to use, key features, and expected output format implying the response structure.

    get_storage_status: `Shows git status of the knowledge datastore.
  
  When to use this tool:
  - Checking for uncommitted changes
  - Verifying sync status with remote
  - Debugging storage issues
  - Understanding current branch
  - Reviewing repository state
  
  Key features:
  - Shows uncommitted file count
  - Displays current branch
  - Shows last commit info
  - Indicates remote sync status
  - Provides detailed git status
  
  You should:
  1. Use before sync operations
  2. Check when changes aren't persisting
  3. Verify remote configuration
  4. Monitor uncommitted changes
  5. Debug sync failures
  
  DO NOT use when:
  - Just need server info
  - Don't need git details
  - Already know status
  
  Returns: {success: bool, storage_path: str, has_changes: bool, current_branch: str, last_commit: str, remote_status: str, uncommitted_files: int, status_details: str}`,