Sage MCP - Academic Research Server

An MCP (Model Context Protocol) server that provides LLMs with access to academic papers and periodicals for research-grounded responses.

Features

• Full-text search across papers using SQLite FTS5
• Topic/publication filtering for targeted research
• Paper retrieval with full content for detailed analysis
• Extensible database - add your own papers programmatically

Tools Available

Tool	Description
search_papers	Semantic/keyword search across all papers
get_paper	Retrieve full paper content by ID
list_topics	Browse available research topics
list_publications	Browse available journals/sources
get_papers_by_topic	Filter papers by topic
get_papers_by_publication	Filter papers by journal
add_paper	Add new papers to the database

---

Quick Start (Local Setup)

Prerequisites

• Node.js 18+ (recommended: 20 LTS)
• npm 9+

1. Clone/Download and Install

cd C:\AIapps\SageMCP   # or your chosen directory
npm install
npm run build

2. Seed the Database

# Option A: Sample papers (10 ML/AI papers)
npm run seed

# Option B: Import from XML (if you have papers_database.xml)
npm run import-xml

3. Verify Installation

npm start
# Should output: "Sage MCP Server running on stdio"
# Press Ctrl+C to stop

---

Connecting to MCP Clients

Claude Desktop (Windows)

1. Locate config file:

   %APPDATA%\Claude\claude_desktop_config.json
   

   Usually: C:\Users\<YourName>\AppData\Roaming\Claude\claude_desktop_config.json

2. Edit the config (create if doesn't exist):

   {
     "mcpServers": {
       "sage": {
         "command": "node",
         "args": ["C:/AIapps/SageMCP/dist/index.js"]
       }
     }
   }
   

3. Restart Claude Desktop completely (quit from system tray, reopen)

4. Verify connection: Look for the hammer 🔨 icon in Claude's chat input - click it to see available tools

Claude Desktop (macOS)

1. Config location:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

2. Config content:

   {
     "mcpServers": {
       "sage": {
         "command": "node",
         "args": ["/Users/<you>/path/to/SageMCP/dist/index.js"]
       }
     }
   }
   

Windsurf / Cascade

Add to your MCP settings (Settings → MCP Servers):

{
  "sage": {
    "command": "node",
    "args": ["C:/AIapps/SageMCP/dist/index.js"]
  }
}

Cline (VS Code Extension)

1. Open VS Code settings
2. Search for "Cline MCP"
3. Add server configuration:

   {
     "sage": {
       "command": "node",
       "args": ["C:/AIapps/SageMCP/dist/index.js"]
     }
   }
   

Custom MCP Client (Programmatic)

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['C:/AIapps/SageMCP/dist/index.js'],
});

const client = new Client({ name: 'my-client', version: '1.0.0' }, {});
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log(tools);

// Call a tool
const result = await client.callTool({
  name: 'search_papers',
  arguments: { query: '神學', limit: 5 }
});
console.log(result);

---

Configuration

Environment Variables

Variable	Description	Default
SAGE_DB_PATH	Custom database file path	./data/sage.db

Example with custom DB path:

{
  "mcpServers": {
    "sage": {
      "command": "node",
      "args": ["C:/AIapps/SageMCP/dist/index.js"],
      "env": {
        "SAGE_DB_PATH": "D:/Research/my_papers.db"
      }
    }
  }
}

---

Adding Your Own Papers

Via the MCP Tool

LLMs can use the add_paper tool directly to add papers.

Via XML Import

Place your XML file in data/ and run:

npm run import-xml -- ./data/your_papers.xml

Programmatically

import { initDb, addPaper } from './dist/db.js';

await initDb();

addPaper({
  title: 'Your Paper Title',
  authors: 'Author One, Author Two',
  abstract: 'Paper abstract...',
  content: 'Full paper content...',
  publication: 'Journal Name',
  publication_date: '2024-01-15',
  doi: '10.1234/example',
  url: 'https://example.com/paper',
  topics: 'Topic1, Topic2',
  keywords: 'keyword1, keyword2, keyword3'
});

---

Database Schema

Papers are stored in SQLite with full-text search indexing:

Field	Type	Description
id	INTEGER	Auto-incrementing primary key
title	TEXT	Paper title
authors	TEXT	Comma-separated author list
abstract	TEXT	Paper abstract
content	TEXT	Full paper text
publication	TEXT	Journal/conference name
publication_date	TEXT	Publication date (YYYY-MM-DD)
doi	TEXT	DOI identifier (optional)
url	TEXT	URL to paper (optional)
topics	TEXT	Comma-separated topics
keywords	TEXT	Comma-separated keywords

---

VPS Deployment

Single command deploys everything (from your local machine):

# Windows PowerShell
.\deploy\deploy.ps1 -VpsHost "user@your-vps.com"

# Linux/macOS
./deploy/deploy.sh user@your-vps.com

This automatically:

1. Installs Node.js and dependencies on VPS
2. Creates sage user and directories
3. Copies source files and database
4. Builds the project
5. Sets up and starts systemd service

Uninstall:

# Windows
.\deploy\uninstall.ps1 -VpsHost "user@your-vps.com"

# Linux/macOS (or directly on VPS)
./deploy/uninstall.sh

See deploy/README.md for detailed options and troubleshooting.

---

Troubleshooting

"Cannot find module" errors

npm run build  # Rebuild TypeScript

Claude Desktop doesn't show tools

1. Check config JSON syntax (use a JSON validator)
2. Ensure path uses forward slashes: C:/path/to/file not C:\path\to\file
3. Restart Claude Desktop completely (quit from system tray)
4. Check Claude's logs: %APPDATA%\Claude\logs\

Database errors

# Reset database
rm -rf data/sage.db
npm run seed  # or npm run import-xml

Test MCP server manually

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

---

License

MIT