# 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
```bash
cd C:\AIapps\SageMCP # or your chosen directory
npm install
npm run build
```
### 2. Seed the Database
```bash
# 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
```bash
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):
```json
{
"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:**
```json
{
"mcpServers": {
"sage": {
"command": "node",
"args": ["/Users/<you>/path/to/SageMCP/dist/index.js"]
}
}
}
```
### Windsurf / Cascade
Add to your MCP settings (Settings → MCP Servers):
```json
{
"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:
```json
{
"sage": {
"command": "node",
"args": ["C:/AIapps/SageMCP/dist/index.js"]
}
}
```
### Custom MCP Client (Programmatic)
```typescript
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:**
```json
{
"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:
```bash
npm run import-xml -- ./data/your_papers.xml
```
### Programmatically
```typescript
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):
```powershell
# 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:**
```powershell
# Windows
.\deploy\uninstall.ps1 -VpsHost "user@your-vps.com"
# Linux/macOS (or directly on VPS)
./deploy/uninstall.sh
```
See [deploy/README.md](deploy/README.md) for detailed options and troubleshooting.
---
## Troubleshooting
### "Cannot find module" errors
```bash
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
```bash
# Reset database
rm -rf data/sage.db
npm run seed # or npm run import-xml
```
### Test MCP server manually
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
```
---
## License
MIT
