How do I use Sage MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Sage MCP Find recent research papers about machine learning interpretability" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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)

Locate config file:
```
%APPDATA%\Claude\claude_desktop_config.json
```
Usually: C:\Users\<YourName>\AppData\Roaming\Claude\claude_desktop_config.json

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

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

Restart Claude Desktop completely (quit from system tray, reopen)
Verify connection: Look for the hammer 🔨 icon in Claude's chat input - click it to see available tools

Claude Desktop (macOS)

Config location:

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

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)

Open VS Code settings
Search for "Cline MCP"

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:

Installs Node.js and dependencies on VPS
Creates sage user and directories
Copies source files and database
Builds the project
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

Check config JSON syntax (use a JSON validator)
Ensure path uses forward slashes: C:/path/to/file not C:\path\to\file
Restart Claude Desktop completely (quit from system tray)
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

Sage MCP