Sor Server

A sample MCP server designed to test context efficiency with LLM clients. Contains 174 backend SOR (System of Record) CRUD tools but exposes only 3 meta-tools to clients.

The Problem

When you expose many tools to an LLM, each tool's name, description, and schema consumes context tokens. With 174 tools and complex schemas, this could easily be 50,000+ tokens just for tool definitions.

The Solution

Instead of exposing all 174 tools directly, this server exposes only 3 meta-tools:

Tool	Purpose
search_tools	Search through tools, returns only relevant ones with filtered schemas
execute_tool	Execute any tool by name with parameters
get_tool_schema	Get detailed schema for a specific tool

Result: ~98% context reduction (~1,000 tokens vs ~50,000 tokens)

---

Quick Start

1. Install dependencies

npm install

2. Add to Claude Desktop

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

Add this to the mcpServers object:

{
  "mcpServers": {
    "sor-mcp-server": {
      "command": "node",
      "args": ["/FULL/PATH/TO/mcp-test/src/index.js"]
    }
  }
}

Important: Replace /FULL/PATH/TO/ with the actual absolute path to this repo.

3. Restart Claude Desktop

• Quit Claude completely (Cmd+Q / Alt+F4)
• Reopen Claude Desktop
• You should see the MCP server connected with 3 tools

---

How It Works

Search Algorithm

1. Pre-built Index: Each tool has searchable text combining name + description + tags
2. Keyword Scoring: Query terms are matched against the index
   • +1.0 for partial match
   • +0.5 bonus for exact word boundary match
3. Schema Filtering: Only schema fields relevant to your query are returned

Example:

Query: "assign ticket user"

Results:
1. ticket_assign (score: 4.5) ← matches all 3 terms
2. ticket_add_watcher (score: 3.0)
3. user_create (score: 1.5)

Schema Filtering

Instead of returning a 60-field ticket schema, it returns only fields matching your query:

Query: "create ticket with priority"

Returns only: id, title, type, status, priority, description
(not: sla, environment, watchers, attachments, etc.)

---

The 3 Exposed Tools

1. search_tools

Search through 174 backend tools with natural language.

{
  "query": "create user with email",
  "limit": 5,
  "include_schema": true,
  "category": "user",
  "operation": "create"
}

Parameters:

Param	Type	Required	Description
query	string	Yes	Natural language search
limit	number	No	Max results (default: 5)
include_schema	boolean	No	Include filtered schemas (default: true)
category	string	No	Filter by entity type
operation	string	No	Filter by: create, read, update, delete, auth, execute

---

2. execute_tool

Execute any backend tool by name.

{
  "tool_name": "user_create",
  "params": {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Parameters:

Param	Type	Required	Description
tool_name	string	Yes	Exact tool name
params	object	Yes	Tool parameters

---

3. get_tool_schema

Get complete or filtered schema for a specific tool.

{
  "tool_name": "ticket_create",
  "query": "priority status"
}

Parameters:

Param	Type	Required	Description
tool_name	string	Yes	Exact tool name
query	string	No	Filter to relevant fields only

---

Backend Tools (174 total)

CRUD Operations (8 per entity × 18 entities = 144 tools)

Operation	Description
{entity}_create	Create a new record
{entity}_get	Get by ID
{entity}_list	List/search with pagination
{entity}_update	Update a record
{entity}_delete	Delete (soft by default)
{entity}_batch_create	Bulk create
{entity}_batch_update	Bulk update
{entity}_batch_delete	Bulk delete

Entities (18)

Category	Entities
Core	User, Organization, Project
Work	Ticket, Comment, Sprint
Config	Workflow, Webhook, SLA Policy
System	Notification, Audit Log, API Key
Extensions	Integration, Custom Field, Tag
Content	Attachment, Report, Time Entry

Special Tools (30 additional)

Category	Tools
Auth	user_authenticate, user_change_password, user_reset_password, user_enable_2fa, user_invite
Org	organization_add_member, organization_remove_member, organization_list_members
Project	project_add_member, project_remove_member, project_get_metrics
Ticket	ticket_assign, ticket_transition, ticket_add_watcher, ticket_link, ticket_log_time, ticket_get_history
Sprint	sprint_start, sprint_complete, sprint_add_issue, sprint_remove_issue, sprint_get_burndown
Reports	report_run, report_export, audit_log_search, audit_log_export
Webhook	webhook_test, webhook_get_deliveries
Notification	notification_mark_read, notification_get_unread_count

---

Schema Complexity

Intentionally complex schemas for realistic testing:

Entity	Fields	Nested Objects
User	24+	preferences, metadata, billing_info
Organization	18+	settings, compliance, billing, limits
Ticket	40+	customer, environment, sla, attachments, linked_issues
Workflow	15+	statuses[], transitions[], automations[]

---

Context Efficiency Comparison

Approach	Est. Tokens	Tools Available
All 174 tools exposed	~50,000+	174
3 meta-tools	~1,000	174 (via search)
Savings	~98%	Same functionality

---

Testing

Run the server directly

npm start

Test search locally

node -e "
import { allTools, toolIndex, toolCount } from './src/tools.js';
console.log('Total tools:', toolCount);
"

---

File Structure

mcp-test/
├── src/
│   ├── index.js      # MCP server, exposes 3 tools
│   ├── tools.js      # 174 backend tool definitions
│   └── schemas.js    # Complex entity schemas
├── package.json
└── README.md

---

License

MIT