Enterprise Internal Knowledge Search via Unified MCP Tools

graph TD
    Agent[AI Agent: tools/call federated_search] --> MCP[Unified Knowledge MCP Server]
    
    subgraph Fan-Out & Aggregation Pipeline
        MCP --> CacheCheck{Check Redis Cache}
        CacheCheck -->|Cache Miss| FanOut[Concurrent API Fan-Out]
        
        FanOut --> Jira[Jira REST API: JQL Search]
        FanOut --> Confluence[Confluence API: CQL Search]
        FanOut --> Notion[Notion API: Search Endpoint]
        
        Jira & Confluence & Notion --> Normalizer[HTML / ADF / Block Stripper]
        Normalizer --> ReRanker[Reciprocal Rank Fusion]
        ReRanker --> Budget[Token Budget Capper: 3,000 Tokens]
    end
    
    Budget --> Markdown[Clean Markdown Synthesis]
    Markdown --> Agent

{
  "name": "enterprise_knowledge_search",
  "description": "Unified semantic and keyword search across Jira tickets, Confluence RFCs, and Notion engineering docs.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search keyword, ticket key (e.g. ENG-104), or natural language query."
      },
      "sources": {
        "type": "array",
        "items": { "type": "string", "enum": ["jira", "confluence", "notion"] },
        "default": ["jira", "confluence", "notion"],
        "description": "SaaS knowledge sources to query."
      },
      "max_results_per_source": {
        "type": "integer",
        "default": 3,
        "maximum": 5
      }
    },
    "required": ["query"]
  }
}

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import TurndownService from 'turndown';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL || 'redis://');
const turndown = new TurndownService();

const server = new Server(
  { name: 'unified-knowledge-mcp', version: '2.0.0' },
  { capabilities: { tools: {} } }
);

// Register Single Unified Tool
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'enterprise_knowledge_search',
      description: 'Search across Jira, Confluence, and Notion with token-efficient markdown synthesis.',
      inputSchema: {
        type: 'object',
        properties: {
          query: { type: 'string', description: 'Search term or ticket identifier.' },
          sources: {
            type: 'array',
            items: { type: 'string', enum: ['jira', 'confluence', 'notion'] },
            default: ['jira', 'confluence', 'notion']
          }
        },
        required: ['query']
      }
    }
  ]
}));

// Tool Execution Handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name !== 'enterprise_knowledge_search') {
    throw new Error(`Tool not found: ${request.params.name}`);
  }

  const { query, sources = ['jira', 'confluence', 'notion'] } = request.params.arguments as any;

  // 1. Check Redis Cache to protect API rate limits
  const cacheKey = `mcp:kb:${query.toLowerCase().trim()}:${sources.sort().join('_')}`;
  const cached = await redis.get(cacheKey);
  if (cached) {
    return { content: [{ type: 'text', text: cached }] };
  }

  // 2. Concurrent Fan-Out across configured APIs
  const tasks: Promise<string[]>[] = [];

  if (sources.includes('jira')) tasks.push(searchJira(query));
  if (sources.includes('confluence')) tasks.push(searchConfluence(query));
  if (sources.includes('notion')) tasks.push(searchNotion(query));

  const results = await Promise.allSettled(tasks);
  const flattened: string[] = [];

  for (const res of results) {
    if (res.status === 'fulfilled') {
      flattened.push(...res.value);
    }
  }

  // 3. Token-Budget Cap (Truncate output to 12,000 characters ~ 3,000 tokens)
  let combinedMarkdown = flattened.join('\n\n---\n\n');
  if (combinedMarkdown.length > 12000) {
    combinedMarkdown = combinedMarkdown.slice(0, 12000) + '\n\n> *[Notice: Remaining results truncated to fit context budget]*';
  }

  if (!combinedMarkdown.trim()) {
    combinedMarkdown = `No documentation or tickets found for query: "${query}"`;
  }

  // Cache result for 15 minutes
  await redis.set(cacheKey, combinedMarkdown, 'EX', 900);

  return { content: [{ type: 'text', text: combinedMarkdown }] };
});

// Jira REST API Search (JQL)
async function searchJira(query: str): Promise<string[]> {
  try {
    const url = `${process.env.JIRA_HOST}/rest/api/3/search?jql=text ~ "${query}" ORDER BY updated DESC&maxResults=3`;
    const res = await fetch(url, {
      headers: {
        'Authorization': `Basic ${Buffer.from(`${process.env.JIRA_EMAIL}:${process.env.JIRA_API_TOKEN}`).toString('base64')}`,
        'Accept': 'application/json'
      }
    });
    if (!res.ok) return [];
    const data = await res.json();
    return (data.issues || []).map((issue: any) => {
      const summary = issue.fields?.summary || '';
      const status = issue.fields?.status?.name || 'Open';
      return `### 🎫 [Jira: ${issue.key}] ${summary}\n**Status:** ${status} | **Link:** ${process.env.JIRA_HOST}/browse/${issue.key}`;
    });
  } catch {
    return [];
  }
}

// Confluence REST API Search (CQL)
async function searchConfluence(query: string): Promise<string[]> {
  try {
    const url = `${process.env.CONFLUENCE_HOST}/wiki/rest/api/content/search?cql=text ~ "${query}"&limit=3&expand=body.storage`;
    const res = await fetch(url, {
      headers: {
        'Authorization': `Basic ${Buffer.from(`${process.env.JIRA_EMAIL}:${process.env.JIRA_API_TOKEN}`).toString('base64')}`,
        'Accept': 'application/json'
      }
    });
    if (!res.ok) return [];
    const data = await res.json();
    return (data.results || []).map((page: any) => {
      const rawHtml = page.body?.storage?.value || '';
      const cleanMarkdown = turndown.turndown(rawHtml).slice(0, 500); // Cap excerpt length
      return `### 📄 [Confluence] ${page.title}\n**URL:** ${process.env.CONFLUENCE_HOST}/wiki${page._links?.webui}\n\n${cleanMarkdown}...`;
    });
  } catch {
    return [];
  }
}

// Notion REST API Search
async function searchNotion(query: string): Promise<string[]> {
  try {
    const res = await fetch('https://api.notion.com/v1/search', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.NOTION_API_KEY}`,
        'Notion-Version': '2022-06-28',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query, page_size: 3 })
    });
    if (!res.ok) return [];
    const data = await res.json();
    return (data.results || []).map((page: any) => {
      const title = page.properties?.title?.title?.[0]?.plain_text || page.properties?.Name?.title?.[0]?.plain_text || 'Untitled Doc';
      return `### 📝 [Notion] ${title}\n**URL:** ${page.url}`;
    });
  } catch {
    return [];
  }
}

async function run() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

run();

{
  "jsonrpc": "2.0",
  "id": "kb-search-991",
  "method": "tools/call",
  "params": {
    "name": "enterprise_knowledge_search",
    "arguments": {
      "query": "OAuth2 Token Exchange RFC",
      "sources": ["jira", "confluence"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "kb-search-991",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "### 🎫 [Jira: SEC-402] Implement RFC 8693 Token Exchange\n**Status:** In Progress | **Link:** https://enterprise.atlassian.net/browse/SEC-402\n\n---\n\n### 📄 [Confluence] RFC-109: Enterprise Agent Authentication Architecture\n**URL:** https://enterprise.atlassian.net/wiki/spaces/ARCH/pages/882194\n\nThis document outlines how autonomous agents delegate scoped sub-tokens using OAuth2 token exchange..."
      }
    ]
  }
}