memory-journal-mcp 3.0.0

package/src/filtering/ToolFilter.ts

@@ -0,0 +1,271 @@
+/**
+ * Memory Journal MCP Server - Tool Filtering
+ * 
+ * Configurable tool filtering system with groups and meta-groups.
+ * Matches mysql-mcp filtering syntax and patterns.
+ */
+
+import type {
+    ToolGroup,
+    MetaGroup,
+    ToolFilterRule,
+    ToolFilterConfig,
+} from '../types/index.js';
+
+// Re-export ToolFilterConfig from types
+export type { ToolFilterConfig } from '../types/index.js';
+
+/**
+ * Tool group definitions mapping group names to tool names
+ * 
+ * All 24 tools are categorized here for filtering support.
+ */
+export const TOOL_GROUPS: Record<ToolGroup, string[]> = {
+    core: [
+        'create_entry',
+        'get_entry_by_id',
+        'get_recent_entries',
+        'create_entry_minimal',
+        'test_simple',
+        'list_tags',
+    ],
+    search: [
+        'search_entries',
+        'search_by_date_range',
+        'semantic_search',
+        'get_vector_index_stats',
+    ],
+    analytics: [
+        'get_statistics',
+        'get_cross_project_insights',
+    ],
+    relationships: [
+        'link_entries',
+        'visualize_relationships',
+    ],
+    export: [
+        'export_entries',
+    ],
+    admin: [
+        'update_entry',
+        'delete_entry',
+        'rebuild_vector_index',
+        'add_to_vector_index',
+    ],
+    github: [
+        'get_github_issues',
+        'get_github_prs',
+        'get_github_issue',
+        'get_github_pr',
+        'get_github_context',
+    ],
+    backup: [
+        'backup_journal',
+        'list_backups',
+        'restore_backup',
+    ],
+};
+
+/**
+ * Meta-group definitions mapping shortcuts to groups
+ */
+export const META_GROUPS: Record<MetaGroup, ToolGroup[]> = {
+    starter: ['core', 'search'],
+    essential: ['core'],
+    full: ['core', 'search', 'analytics', 'relationships', 'export', 'admin', 'github', 'backup'],
+    readonly: ['core', 'search', 'analytics', 'relationships', 'export'],
+};
+
+/**
+ * Get all tool names across all groups
+ */
+export function getAllToolNames(): string[] {
+    const allTools: string[] = [];
+    for (const tools of Object.values(TOOL_GROUPS)) {
+        allTools.push(...tools);
+    }
+    return allTools;
+}
+
+/**
+ * Get the group for a specific tool
+ */
+export function getToolGroup(toolName: string): ToolGroup | undefined {
+    for (const [group, tools] of Object.entries(TOOL_GROUPS)) {
+        if (tools.includes(toolName)) {
+            return group as ToolGroup;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Check if a string is a valid group name
+ */
+function isGroup(name: string): name is ToolGroup {
+    return name in TOOL_GROUPS;
+}
+
+/**
+ * Check if a string is a valid meta-group name
+ */
+function isMetaGroup(name: string): name is MetaGroup {
+    return name in META_GROUPS;
+}
+
+/**
+ * Parse a tool filter string into configuration
+ * 
+ * Syntax:
+ * - `starter` - Use starter preset (whitelist mode)
+ * - `core,search` - Enable specific groups (whitelist mode)
+ * - `full,-admin` - All tools except admin group
+ * - `starter,-delete_entry` - Starter without specific tool
+ * - `+semantic_search` - Add specific tool to current set
+ */
+export function parseToolFilter(filterString: string): ToolFilterConfig {
+    const rules: ToolFilterRule[] = [];
+    const parts = filterString.split(',').map(p => p.trim()).filter(Boolean);
+
+    // Determine if we're in whitelist or blacklist mode
+    // If first item has no prefix and is a group/metagroup, we're in whitelist mode
+    let enabledTools = new Set<string>();
+    let isWhitelistMode = false;
+
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (!part) continue;
+
+        const isAdd = part.startsWith('+');
+        const isRemove = part.startsWith('-');
+        const name = (isAdd || isRemove) ? part.slice(1) : part;
+
+        if (i === 0 && !isAdd && !isRemove) {
+            // First item without prefix - whitelist mode
+            isWhitelistMode = true;
+
+            if (isMetaGroup(name)) {
+                // Expand meta-group to groups
+                for (const group of META_GROUPS[name]) {
+                    enabledTools = new Set([...enabledTools, ...TOOL_GROUPS[group]]);
+                }
+            } else if (isGroup(name)) {
+                enabledTools = new Set([...enabledTools, ...TOOL_GROUPS[name]]);
+            } else {
+                // Single tool
+                enabledTools.add(name);
+            }
+
+            rules.push({
+                type: 'include',
+                target: name,
+                isGroup: isGroup(name) || isMetaGroup(name),
+            });
+        } else if (isRemove) {
+            // Remove group or tool
+            if (isGroup(name)) {
+                for (const tool of TOOL_GROUPS[name]) {
+                    enabledTools.delete(tool);
+                }
+            } else {
+                enabledTools.delete(name);
+            }
+
+            rules.push({
+                type: 'exclude',
+                target: name,
+                isGroup: isGroup(name),
+            });
+        } else {
+            // Add group or tool (with or without + prefix)
+            if (isMetaGroup(name)) {
+                for (const group of META_GROUPS[name]) {
+                    enabledTools = new Set([...enabledTools, ...TOOL_GROUPS[group]]);
+                }
+            } else if (isGroup(name)) {
+                enabledTools = new Set([...enabledTools, ...TOOL_GROUPS[name]]);
+            } else {
+                enabledTools.add(name);
+            }
+
+            rules.push({
+                type: 'include',
+                target: name,
+                isGroup: isGroup(name) || isMetaGroup(name),
+            });
+        }
+    }
+
+    // If no filter specified or starting with removal, start with all tools
+    if (!isWhitelistMode && rules.length > 0 && rules[0]?.type === 'exclude') {
+        enabledTools = new Set(getAllToolNames());
+        // Re-apply rules
+        for (const rule of rules) {
+            if (rule.type === 'exclude') {
+                if (isGroup(rule.target)) {
+                    for (const tool of TOOL_GROUPS[rule.target]) {
+                        enabledTools.delete(tool);
+                    }
+                } else {
+                    enabledTools.delete(rule.target);
+                }
+            }
+        }
+    }
+
+    return {
+        raw: filterString,
+        rules,
+        enabledTools,
+    };
+}
+
+/**
+ * Check if a tool is enabled based on filter string
+ */
+export function isToolEnabled(toolName: string, filterConfig: ToolFilterConfig): boolean {
+    return filterConfig.enabledTools.has(toolName);
+}
+
+/**
+ * Filter tools array based on filter configuration
+ */
+export function filterTools<T extends { name: string }>(
+    tools: T[],
+    filterConfig: ToolFilterConfig
+): T[] {
+    return tools.filter(tool => isToolEnabled(tool.name, filterConfig));
+}
+
+/**
+ * Get tool filter from environment variable
+ */
+export function getToolFilterFromEnv(): ToolFilterConfig | null {
+    const filterString = process.env['MEMORY_JOURNAL_MCP_TOOL_FILTER'];
+    if (!filterString) return null;
+    return parseToolFilter(filterString);
+}
+
+/**
+ * Calculate token savings from filtering
+ */
+export function calculateTokenSavings(
+    totalTools: number,
+    enabledTools: number,
+    avgTokensPerTool = 150
+): { reduction: number; savedTokens: number } {
+    const savedTokens = (totalTools - enabledTools) * avgTokensPerTool;
+    const reduction = ((totalTools - enabledTools) / totalTools) * 100;
+    return { reduction, savedTokens };
+}
+
+/**
+ * Get human-readable filter summary
+ */
+export function getFilterSummary(filterConfig: ToolFilterConfig): string {
+    const total = getAllToolNames().length;
+    const enabled = filterConfig.enabledTools.size;
+    const { reduction } = calculateTokenSavings(total, enabled);
+
+    return `${enabled}/${total} tools enabled (${reduction.toFixed(0)}% reduction)`;
+}

package/src/github/GitHubIntegration.ts

@@ -0,0 +1,409 @@
+/**
+ * Memory Journal MCP Server - GitHub Integration
+ * 
+ * GitHub API integration using @octokit/rest for API access
+ * and simple-git for local repository operations.
+ */
+
+import { Octokit } from '@octokit/rest';
+import * as simpleGitImport from 'simple-git';
+import { logger } from '../utils/logger.js';
+import type {
+    GitHubIssue,
+    GitHubPullRequest,
+    GitHubWorkflowRun,
+    ProjectContext,
+} from '../types/index.js';
+
+// Handle simpleGit ESM/CJS interop
+type SimpleGitType = typeof simpleGitImport.simpleGit;
+const simpleGit: SimpleGitType = simpleGitImport.simpleGit;
+
+/**
+ * Local repository information
+ */
+export interface RepoInfo {
+    owner: string | null;
+    repo: string | null;
+    branch: string | null;
+    remoteUrl: string | null;
+}
+
+/**
+ * GitHub issue details (extended)
+ */
+export interface IssueDetails extends GitHubIssue {
+    body: string | null;
+    labels: string[];
+    assignees: string[];
+    createdAt: string;
+    updatedAt: string;
+    closedAt: string | null;
+    commentsCount: number;
+}
+
+/**
+ * GitHub PR details (extended)
+ */
+export interface PullRequestDetails extends GitHubPullRequest {
+    body: string | null;
+    draft: boolean;
+    headBranch: string;
+    baseBranch: string;
+    author: string;
+    createdAt: string;
+    updatedAt: string;
+    mergedAt: string | null;
+    closedAt: string | null;
+    additions: number;
+    deletions: number;
+    changedFiles: number;
+}
+
+/**
+ * GitHubIntegration - Handles GitHub API and local git operations
+ */
+export class GitHubIntegration {
+    private octokit: Octokit | null = null;
+    private git: simpleGitImport.SimpleGit;
+    private readonly token: string | undefined;
+
+    constructor(workingDir = '.') {
+        this.token = process.env['GITHUB_TOKEN'];
+
+        // Use GITHUB_REPO_PATH env var if set, otherwise fall back to workingDir
+        const envRepoPath = process.env['GITHUB_REPO_PATH'];
+        const effectiveDir = envRepoPath || workingDir;
+
+        // Resolve and log the actual working directory
+        const resolvedDir = effectiveDir === '.' ? process.cwd() : effectiveDir;
+        logger.info('GitHub integration using directory', {
+            module: 'GitHub',
+            workingDir,
+            envRepoPath: envRepoPath ?? 'not set',
+            effectiveDir,
+            resolvedDir,
+            cwd: process.cwd()
+        });
+
+        this.git = simpleGit(effectiveDir);
+
+        // Initialize Octokit if token is available
+        if (this.token) {
+            this.octokit = new Octokit({ auth: this.token });
+            logger.info('GitHub integration initialized with token', { module: 'GitHub' });
+        } else {
+            logger.info('GitHub integration initialized without token (limited functionality)', { module: 'GitHub' });
+        }
+    }
+
+    /**
+     * Check if GitHub API is available (token present)
+     */
+    isApiAvailable(): boolean {
+        return this.octokit !== null;
+    }
+
+    /**
+     * Get local repository information
+     */
+    async getRepoInfo(): Promise<RepoInfo> {
+        try {
+            // Get current branch
+            const branchResult = await this.git.branch();
+            const branch = branchResult.current || null;
+
+            // Get remote URL
+            const remotes = await this.git.getRemotes(true);
+            const origin = remotes.find(r => r.name === 'origin');
+            const remoteUrl = origin?.refs?.fetch || null;
+
+            // Parse owner/repo from remote URL
+            const { owner, repo } = this.parseRemoteUrl(remoteUrl);
+
+            return { owner, repo, branch, remoteUrl };
+        } catch (error) {
+            logger.debug('Failed to get repo info (may not be a git repo)', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return { owner: null, repo: null, branch: null, remoteUrl: null };
+        }
+    }
+
+    /**
+     * Parse owner and repo from GitHub remote URL
+     */
+    private parseRemoteUrl(remoteUrl: string | null): { owner: string | null; repo: string | null } {
+        if (!remoteUrl) return { owner: null, repo: null };
+
+        // Handle SSH format: git@github.com:owner/repo.git
+        if (remoteUrl.startsWith('git@github.com:')) {
+            const pathPart = remoteUrl.replace('git@github.com:', '').replace('.git', '');
+            const parts = pathPart.split('/');
+            if (parts.length >= 2) {
+                return { owner: parts[0] ?? null, repo: parts[1] ?? null };
+            }
+        }
+
+        // Handle HTTPS format: https://github.com/owner/repo.git
+        try {
+            const url = new URL(remoteUrl);
+            if (url.hostname === 'github.com') {
+                const path = url.pathname.replace('.git', '').replace(/^\//, '');
+                const parts = path.split('/');
+                if (parts.length >= 2) {
+                    return { owner: parts[0] ?? null, repo: parts[1] ?? null };
+                }
+            }
+        } catch {
+            // Not a valid URL
+        }
+
+        return { owner: null, repo: null };
+    }
+
+    /**
+     * Get repository issues
+     */
+    async getIssues(
+        owner: string,
+        repo: string,
+        state: 'open' | 'closed' | 'all' = 'open',
+        limit = 20
+    ): Promise<GitHubIssue[]> {
+        if (!this.octokit) {
+            return [];
+        }
+
+        try {
+            const response = await this.octokit.issues.listForRepo({
+                owner,
+                repo,
+                state,
+                per_page: limit,
+                sort: 'updated',
+                direction: 'desc',
+            });
+
+            // Filter out pull requests (GitHub API includes PRs in issues)
+            return response.data
+                .filter(issue => !issue.pull_request)
+                .map(issue => ({
+                    number: issue.number,
+                    title: issue.title,
+                    url: issue.html_url,
+                    state: issue.state === 'open' ? 'OPEN' : 'CLOSED',
+                }));
+        } catch (error) {
+            logger.error('Failed to get issues', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return [];
+        }
+    }
+
+    /**
+     * Get issue details
+     */
+    async getIssue(owner: string, repo: string, issueNumber: number): Promise<IssueDetails | null> {
+        if (!this.octokit) {
+            return null;
+        }
+
+        try {
+            const response = await this.octokit.issues.get({
+                owner,
+                repo,
+                issue_number: issueNumber,
+            });
+
+            const issue = response.data;
+
+            // Verify it's not a PR
+            if (issue.pull_request) {
+                return null;
+            }
+
+            return {
+                number: issue.number,
+                title: issue.title,
+                url: issue.html_url,
+                state: issue.state === 'open' ? 'OPEN' : 'CLOSED',
+                body: issue.body ?? null,
+                labels: issue.labels.map(l => (typeof l === 'string' ? l : l.name ?? '')),
+                assignees: issue.assignees?.map(a => a.login) ?? [],
+                createdAt: issue.created_at,
+                updatedAt: issue.updated_at,
+                closedAt: issue.closed_at,
+                commentsCount: issue.comments,
+            };
+        } catch (error) {
+            logger.error('Failed to get issue details', {
+                module: 'GitHub',
+                entityId: issueNumber,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return null;
+        }
+    }
+
+    /**
+     * Get repository pull requests
+     */
+    async getPullRequests(
+        owner: string,
+        repo: string,
+        state: 'open' | 'closed' | 'all' = 'open',
+        limit = 20
+    ): Promise<GitHubPullRequest[]> {
+        if (!this.octokit) {
+            return [];
+        }
+
+        try {
+            const response = await this.octokit.pulls.list({
+                owner,
+                repo,
+                state,
+                per_page: limit,
+                sort: 'updated',
+                direction: 'desc',
+            });
+
+            return response.data.map(pr => ({
+                number: pr.number,
+                title: pr.title,
+                url: pr.html_url,
+                state: pr.merged_at ? 'MERGED' : (pr.state === 'open' ? 'OPEN' : 'CLOSED'),
+            }));
+        } catch (error) {
+            logger.error('Failed to get pull requests', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return [];
+        }
+    }
+
+    /**
+     * Get PR details
+     */
+    async getPullRequest(owner: string, repo: string, prNumber: number): Promise<PullRequestDetails | null> {
+        if (!this.octokit) {
+            return null;
+        }
+
+        try {
+            const response = await this.octokit.pulls.get({
+                owner,
+                repo,
+                pull_number: prNumber,
+            });
+
+            const pr = response.data;
+
+            return {
+                number: pr.number,
+                title: pr.title,
+                url: pr.html_url,
+                state: pr.merged_at ? 'MERGED' : (pr.state === 'open' ? 'OPEN' : 'CLOSED'),
+                body: pr.body,
+                draft: pr.draft ?? false,
+                headBranch: pr.head.ref,
+                baseBranch: pr.base.ref,
+                author: pr.user?.login ?? 'unknown',
+                createdAt: pr.created_at,
+                updatedAt: pr.updated_at,
+                mergedAt: pr.merged_at,
+                closedAt: pr.closed_at,
+                additions: pr.additions,
+                deletions: pr.deletions,
+                changedFiles: pr.changed_files,
+            };
+        } catch (error) {
+            logger.error('Failed to get PR details', {
+                module: 'GitHub',
+                entityId: prNumber,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return null;
+        }
+    }
+
+    /**
+     * Get workflow runs from GitHub Actions
+     */
+    async getWorkflowRuns(
+        owner: string,
+        repo: string,
+        limit = 10
+    ): Promise<GitHubWorkflowRun[]> {
+        if (!this.octokit) {
+            logger.debug('GitHub API not available - no token', { module: 'GitHub' });
+            return [];
+        }
+
+        try {
+            const response = await this.octokit.rest.actions.listWorkflowRunsForRepo({
+                owner,
+                repo,
+                per_page: limit,
+            });
+
+            return response.data.workflow_runs.map(run => ({
+                id: run.id,
+                name: run.name ?? 'Unknown Workflow',
+                status: run.status as 'queued' | 'in_progress' | 'completed',
+                conclusion: run.conclusion as 'success' | 'failure' | 'cancelled' | 'skipped' | null,
+                url: run.html_url,
+                headBranch: run.head_branch ?? '',
+                headSha: run.head_sha,
+                createdAt: run.created_at,
+                updatedAt: run.updated_at,
+            }));
+        } catch (error) {
+            logger.error('Failed to get workflow runs', {
+                module: 'GitHub',
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+
+    /**
+     * Get full repository context (issues, PRs, branch info)
+     */
+    async getRepoContext(): Promise<ProjectContext> {
+        const repoInfo = await this.getRepoInfo();
+
+        const context: ProjectContext = {
+            repoName: repoInfo.repo,
+            branch: repoInfo.branch,
+            commit: null,
+            remoteUrl: repoInfo.remoteUrl,
+            projects: [],
+            issues: [],
+            pullRequests: [],
+            workflowRuns: [],
+        };
+
+        // Get current commit
+        try {
+            const log = await this.git.log({ maxCount: 1 });
+            context.commit = log.latest?.hash ?? null;
+        } catch {
+            // Ignore error
+        }
+
+        // Get issues, PRs, and workflow runs if we have owner/repo
+        if (repoInfo.owner && repoInfo.repo) {
+            context.issues = await this.getIssues(repoInfo.owner, repoInfo.repo, 'open', 10);
+            context.pullRequests = await this.getPullRequests(repoInfo.owner, repoInfo.repo, 'open', 10);
+            context.workflowRuns = await this.getWorkflowRuns(repoInfo.owner, repoInfo.repo, 10);
+        }
+
+        return context;
+    }
+}