@mehmetbaykar/swift-poe-search-mcp 1.0.0

package/README.md

@@ -0,0 +1,521 @@
+# Swift Poe Search MCP
+
+A Swift MCP (Model Context Protocol) server providing AI-powered search and research tools via the Poe API proxy. Supports 4 providers with 16 specialized tools.
+
+## Overview
+
+This server acts as a bridge between MCP clients and multiple AI/search providers through Poe's unified API:
+
+| Provider | Tools | Description |
+|----------|-------|-------------|
+| Perplexity | 3 | Web search with citations, reasoning, deep research |
+| Reka | 3 | Agentic research, fact-checking, similarity finding |
+| Exa | 9 | Neural search, code context, company research, crawling |
+| Linkup | 1 | #1 ranked factual accuracy on OpenAI's SimpleQA |
+
+## Quick Start
+
+### Requirements
+
+- Poe subscription with API access
+- API key from [poe.com/api_key](https://poe.com/api_key)
+- **Linux**: Ubuntu 20.04+ or Debian 11+, requires `apt-get install libcurl4`
+- **macOS**: macOS 14+ (Sonoma), Intel Macs supported via Rosetta
+- **Swift**: 6.2+ (for building from source)
+
+### Installation
+
+**Via NPM (no build required):**
+```bash
+npx @mehmetbaykar/swift-poe-search-mcp@latest
+```
+
+**Via Swift (build from source):**
+```bash
+git clone <repo>
+cd swift-poe-search-mcp
+swift build -c release
+```
+
+### Configuration
+
+```bash
+# Required
+export POE_API_KEY=your_api_key
+
+# Optional
+export POE_BASE_URL=https://api.poe.com/v1  # default
+export POE_TIMEOUT_MS=600000                 # default: 10 minutes
+export ENABLED_PROVIDERS=perplexity,reka,exa,linkup  # default: all
+```
+
+### MCP Client Configuration
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "swift-poe-search": {
+      "command": "npx",
+      "args": ["@mehmetbaykar/swift-poe-search-mcp@latest"],
+      "env": {
+        "POE_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "swift-poe-search": {
+      "command": "npx",
+      "args": ["@mehmetbaykar/swift-poe-search-mcp@latest"],
+      "env": {
+        "POE_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code CLI
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "swift-poe-search": {
+      "command": "npx",
+      "args": ["@mehmetbaykar/swift-poe-search-mcp@latest"],
+      "env": {
+        "POE_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Testing with MCP Inspector
+
+```bash
+POE_API_KEY=your_key npx @modelcontextprotocol/inspector@latest swift run
+```
+
+---
+
+## Available Tools
+
+### Perplexity Tools
+
+#### `perplexity_ask`
+
+Conversational web search using Sonar API with 200k context.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| messages | [Message] | required | Conversation messages |
+| searchContextSize | enum | low | low, medium, high |
+| searchMode | enum | default | default, academic, sec |
+| searchDomainFilter | string | "" | Comma-separated domains (prefix with `-` to exclude) |
+| searchLanguageFilter | string | "" | ISO 639-1 codes (max 10) |
+| searchRecencyFilter | enum | none | none, day, week, month, year |
+| searchAfterDate | string | "" | Publication date filter |
+| searchBeforeDate | string | "" | Publication date filter |
+| country | string | "" | ISO 3166-1 alpha-2 code |
+| region | string | "" | State/Province name |
+| city | string | "" | City name |
+| latitude | string | "" | Requires longitude + country |
+| longitude | string | "" | Requires latitude + country |
+| returnImages | bool | false | Include images |
+| returnVideos | bool | false | Include videos |
+| imageDomainFilter | string | "" | Domains for images (max 10) |
+| imageFormatFilter | string | "" | gif, jpg, png, webp |
+
+#### `perplexity_reason`
+
+R1-1776 reasoning with web search via Sonar Reasoning Pro (128k context).
+
+All parameters from `perplexity_ask` plus:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| showThinking | bool | false | Show `<think>...</think>` reasoning tags |
+
+#### `perplexity_research`
+
+Deep multi-step research via Perplexity Deep Research (128k context).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| messages | [Message] | required | Conversation messages |
+| showThinking | bool | false | Show reasoning tags |
+| reasoningEffort | enum | low | low, medium, high |
+| searchMode | enum | default | Only "default" supported |
+| searchDomainFilter | string | "" | Comma-separated domains |
+| searchAfterDateFilter | string | "" | Date filter |
+| searchBeforeDateFilter | string | "" | Date filter |
+| lastUpdatedAfterFilter | string | "" | Update date filter |
+| lastUpdatedBeforeFilter | string | "" | Update date filter |
+
+---
+
+### Reka Tools
+
+#### `reka_research`
+
+Autonomous research agent with multi-hop web synthesis.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| messages | [Message] | required | Conversation messages |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `reka_verify_claim`
+
+Fact-check claims with structured verdict, confidence, and reasoning.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| claim | string | required | Statement to verify |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `reka_find_similar`
+
+Find items similar to a target based on specific attributes.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| target | string | required | Item to find similarities for |
+| attribute | string | required | Characteristic to compare (e.g., "functionality", "style") |
+| showThinking | bool | false | Show reasoning tags |
+
+---
+
+### Exa Tools
+
+#### `exa_web_search`
+
+Real-time web search with extensive filtering options.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| query | string | required | Search query |
+| numResults | int | 10 | Results count (1-100) |
+| searchType | enum | auto | auto, neural, deep, fast |
+| category | enum | "" | company, research paper, news, pdf, github, tweet, etc. |
+| showContent | bool | false | Display full page content |
+| includeDomains | string | "" | Domains to include |
+| excludeDomains | string | "" | Domains to exclude |
+| includeText | string | "" | Required text (max 5 words) |
+| excludeText | string | "" | Excluded text (max 5 words) |
+| startCrawlDate | string | "" | ISO 8601 date |
+| endCrawlDate | string | "" | ISO 8601 date |
+| startPublishedDate | string | "" | ISO 8601 date |
+| endPublishedDate | string | "" | ISO 8601 date |
+| returnText | bool | true | Fetch page text |
+| textMaxChars | string | "" | Limit text length |
+| includeHtmlTags | bool | false | Preserve HTML structure |
+| returnHighlights | bool | false | AI-selected key snippets |
+| highlightsSentences | int | 3 | Sentences per highlight (1-10) |
+| highlightsPerUrl | int | 3 | Highlights per result (1-10) |
+| highlightsQuery | string | "" | Guide highlight selection |
+| returnSummary | bool | false | AI-generated summaries |
+| summaryQuery | string | "" | Guide summary generation |
+| livecrawl | enum | fallback | fallback, never, always, preferred |
+| subpages | int | 0 | Linked subpages (0-10) |
+| subpageTarget | string | "" | Keyword for subpages |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `exa_deep_search`
+
+Comprehensive search with automatic query expansion using deep mode.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| objective | string | required | Natural language search description |
+| searchQueries | string | "" | Optional keyword queries (comma-separated, max 5) |
+
+Plus all filtering parameters from `exa_web_search`.
+
+#### `exa_code_context`
+
+Code examples and API documentation search.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| query | string | required | Code/API search query |
+| codeTokens | enum | dynamic | dynamic, 5000, 10000, 20000 |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `exa_crawl_url`
+
+Extract content from specific URLs.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| url | string | required | URL to crawl |
+| maxCharacters | int | 3000 | Max characters to extract |
+| returnText | bool | true | Fetch page text |
+| includeHtmlTags | bool | false | Preserve HTML |
+| returnHighlights | bool | false | Key snippets |
+| highlightsSentences | int | 3 | Sentences per highlight |
+| highlightsPerUrl | int | 3 | Highlights per result |
+| highlightsQuery | string | "" | Guide highlights |
+| returnSummary | bool | false | AI summaries |
+| summaryQuery | string | "" | Guide summaries |
+| livecrawl | enum | preferred | fallback, never, always, preferred |
+| subpages | int | 0 | Linked subpages |
+| subpageTarget | string | "" | Subpage keyword |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `exa_find_similar`
+
+Find pages similar to a given URL.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| url | string | required | Source URL |
+| numResults | int | 10 | Results count (1-100) |
+| category | enum | "" | Content category filter |
+| includeDomains | string | "" | Domains to include |
+| excludeDomains | string | "" | Domains to exclude |
+
+Plus content extraction parameters (returnText, highlights, summaries, livecrawl, subpages).
+
+#### `exa_company_research`
+
+Company research with curated business sources.
+
+Pre-configured domains: bloomberg.com, reuters.com, crunchbase.com, sec.gov, linkedin.com, forbes.com, businesswire.com, prnewswire.com
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| companyName | string | required | Company to research |
+| numResults | int | 5 | Results count |
+| startPublishedDate | string | "" | ISO 8601 date |
+| endPublishedDate | string | "" | ISO 8601 date |
+| returnText | bool | true | Fetch page text |
+| returnHighlights | bool | false | Key snippets |
+| returnSummary | bool | false | AI summaries |
+| livecrawl | enum | fallback | Content freshness |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `exa_linkedin_search`
+
+LinkedIn-specific search for profiles and companies.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| query | string | required | LinkedIn search query |
+| searchType | enum | all | profiles, companies, all |
+| numResults | int | 5 | Results count |
+| returnText | bool | true | Fetch page text |
+| returnHighlights | bool | false | Key snippets |
+| returnSummary | bool | false | AI summaries |
+| livecrawl | enum | fallback | Content freshness |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `exa_quick_answer`
+
+Quick LLM answer with search-backed citations.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| query | string | required | Question to answer |
+| showText | bool | false | Show text under citations |
+| showThinking | bool | false | Show reasoning tags |
+
+#### `exa_deep_research`
+
+Comprehensive AI-powered research agent.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| instructions | string | required | Research question/instructions |
+| model | enum | exa-research | exa-research (15-45s), exa-research-pro (45s-2min), exa-research-fast |
+| showThinking | bool | false | Show reasoning tags |
+
+---
+
+### Linkup Tools
+
+#### `linkup_search`
+
+Factually accurate web search (ranked #1 on OpenAI's SimpleQA benchmark).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| messages | [Message] | required | Conversation messages |
+| depth | enum | standard | standard (fast), deep (comprehensive) |
+
+---
+
+## Development
+
+### Project Structure
+
+```
+Sources/
+├── Core/
+│   ├── API/
+│   │   ├── Config.swift           # Environment configuration
+│   │   ├── PoeAPIClient.swift     # HTTP client
+│   │   └── PoeTypes.swift         # Request/response models
+│   ├── Helpers/
+│   │   ├── ContentStripper.swift  # Strips <think> tags
+│   │   └── With.swift             # Functional builder
+│   ├── Providers/
+│   │   ├── ToolProvider.swift     # Tool factory
+│   │   ├── ServerProvider.swift   # MCP server setup
+│   │   └── ...                    # Other providers
+│   ├── Tools/Search/
+│   │   ├── Perplexity/            # 3 tools
+│   │   ├── Reka/                  # 3 tools
+│   │   ├── Exa/                   # 9 tools
+│   │   └── Linkup/                # 1 tool
+│   └── Environment.swift          # @TaskLocal DI
+└── swift-poe-search-mcp/
+    └── swift_search_mcp.swift     # Entry point
+
+Tests/
+├── Perplexity/
+├── Reka/
+├── Exa/
+├── Linkup/
+└── Environment/                   # Test utilities
+```
+
+### Testing
+
+```bash
+# Run all tests
+POE_API_KEY=your_key swift test
+
+# Run specific provider tests
+POE_API_KEY=your_key swift test --filter "PerplexityToolTests"
+POE_API_KEY=your_key swift test --filter "ExaToolsTests"
+
+# Run specific tool test
+POE_API_KEY=your_key swift test --filter "webSearchTool"
+```
+
+**Test Architecture:**
+- Framework: Swift Testing (`@Test`, `@Suite`)
+- Pattern: `@TaskLocal` environment injection for test isolation
+- Type: Integration tests with real API calls
+
+### Adding New Tools
+
+1. Create tool file in appropriate provider directory:
+
+```swift
+import Foundation
+import MCPToolkit
+
+struct MyNewTool: MCPTool {
+  let name = "my_new_tool"
+  let description: String? = "Tool description"
+
+  @Schemable
+  @ObjectOptions(.additionalProperties { false })
+  struct Parameters: Sendable {
+    let query: String
+    let showThinking: Bool?
+  }
+
+  func call(with arguments: Parameters) async throws(ToolError) -> Content {
+    let model = "model-name"
+    let messages = [PoeMessage(role: "user", content: arguments.query)]
+
+    do {
+      let response = try await Environment.current.poeAPIClient().performChatCompletion(
+        messages,
+        model,
+        nil,  // extra_body parameters
+        !(arguments.showThinking ?? false)
+      )
+      return [ToolContentItem(text: response.content)]
+    } catch let error as PoeError {
+      throw ToolError(error.localizedDescription)
+    }
+  }
+}
+```
+
+2. Register in `ToolProvider.swift`:
+
+```swift
+if config.isProviderEnabled(.myProvider) {
+  tools += [MyNewTool()]
+}
+```
+
+3. Add test in `Tests/MyProvider/MyProviderToolTests.swift`:
+
+```swift
+import Testing
+@testable import Core
+
+@Suite(.testEnvironment)
+struct MyProviderToolTests {
+  @Test func myNewTool() async throws {
+    let tool = MyNewTool()
+    let result = try await tool.call(with: .init(query: "test"))
+    #expect(!result.isEmpty)
+  }
+}
+```
+
+---
+
+## API Reference
+
+### Base Configuration
+
+- **URL**: `https://api.poe.com/v1`
+- **Format**: OpenAI-compatible `/v1/chat/completions`
+- **Auth**: Bearer token via `Authorization` header
+- **Custom params**: Via `extra_body` field
+
+### Message Format
+
+```swift
+struct PoeMessage {
+  let role: String    // "user", "assistant", "system"
+  let content: String
+}
+```
+
+### Response Format
+
+```swift
+struct PoeResponse {
+  let content: String
+  let citations: [String]?
+  let usage: TokenUsage?
+}
+```
+
+---
+
+## Troubleshooting
+
+- **libcurl error on Linux**: Run `apt-get install libcurl4`
+- **Platform not supported**: Only linux-x64 and darwin-arm64 (macOS 14+) are supported
+- **Issues**: [GitHub Issues](https://github.com/mehmetbaykar/swift-poe-search-mcp/issues)
+
+---
+
+## License
+
+MIT

package/bin.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+const { spawn } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const BINARY_NAME = "swift-poe-search-mcp";
+
+function getPlatformKey() {
+  const platform = os.platform();
+  if (platform === "darwin") return "darwin-arm64";
+  if (platform === "linux") return "linux-x64";
+  return null;
+}
+
+function getBinaryPath() {
+  // 1. Local dev: .build/release or .build/debug
+  const devPaths = [
+    path.join(__dirname, ".build", "release", BINARY_NAME),
+    path.join(__dirname, ".build", "debug", BINARY_NAME),
+  ];
+  for (const p of devPaths) {
+    if (fs.existsSync(p)) return p;
+  }
+
+  // 2. Installed: bin/<platform>/swift-poe-search-mcp
+  const platformKey = getPlatformKey();
+  if (platformKey) {
+    const platformPath = path.join(__dirname, "bin", platformKey, BINARY_NAME);
+    if (fs.existsSync(platformPath)) return platformPath;
+  }
+
+  // 3. Legacy fallback: bin/swift-poe-search-mcp
+  const legacyPath = path.join(__dirname, "bin", BINARY_NAME);
+  if (fs.existsSync(legacyPath)) return legacyPath;
+
+  console.error(
+    `Error: Binary not found for platform: ${os.platform()}-${os.arch()}`
+  );
+  console.error("");
+  console.error("Supported platforms:");
+  console.error("  - linux-x64 (Ubuntu 20.04+, Debian 11+)");
+  console.error("  - darwin-arm64 (macOS 14+, Intel via Rosetta)");
+  console.error("");
+  console.error("Note: Windows and Alpine Linux are not supported.");
+  process.exit(1);
+}
+
+const child = spawn(getBinaryPath(), process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("error", (err) => {
+  if (err.message.includes("libcurl")) {
+    console.error("Missing libcurl. Run: apt-get install libcurl4");
+  } else {
+    console.error(`Failed to start: ${err.message}`);
+  }
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mehmetbaykar/swift-poe-search-mcp",
+  "version": "1.0.0",
+  "description": "Swift MCP Server - Model Context Protocol server written in Swift",
+  "author": "Mehmet Baykar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mehmetbaykar/swift-poe-search-mcp.git"
+  },
+  "bin": {
+    "swift-poe-search-mcp": "bin.js"
+  },
+  "scripts": {
+    "build": "swift build",
+    "start": "swift build && node bin.js"
+  },
+  "files": [
+    "bin.js",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "swift",
+    "ai",
+    "perplexity",
+    "exa",
+    "search"
+  ]
+}