Onspring MCP Server

A Model Context Protocol (MCP) server implementation that integrates with Onspring's API, allowing AI assistants to access and manipulate data stored in Onspring instances.

Description

This server provides a bridge between AI assistants and Onspring instances through the Model Context Protocol. It enables MCP clients to read and interact with your Onspring data, providing capabilities like:

• Retrieving lists of apps and their fields
• Fetching records from apps
• Running queries against apps
• Accessing report data
• Retrieve files from attachment fields

Table of Contents

• Installation
• Usage
• Configuration
• Available Tools
• Development
• License

Installation

Prerequisites

• Node.js
• An Onspring instance with API access
• An Onspring API key with appropriate permissions

Installation Steps

1. Install the package globally:

npm install -g @stevanfreeborn/onx-mcp-server

Or use it directly via npx:

npx @stevanfreeborn/onx-mcp-server

Building from Source

If you want to build from source:

# Clone the repository
git clone https://github.com/your-username/onx-mcp-server.git
cd onx-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Usage

In order to use the server, you will need to configure it in the MCP client of your choice. Each MCP client should provide instructions on setting up a MCP server. You will also need to make sure the required environment variables are set. See the Configuration section for more details.

Configuration

The server requires that the following environment variables are set:

| Variable | Description | Default | | ------------------- | --------------------------------- | -------------------------- | | ONSPRING_API_KEY | Your Onspring API key | (Required) | | ONSPRING_BASE_URL | The base URL for the Onspring API | https://api.onspring.com |

Connecting to Claude Desktop

Claude Desktop is a popular MCP client. To connect the Onspring MCP server to Claude Desktop, follow these steps:

1. Find the claude_desktop_config.json file. Please reference this documentation for more information on where to find this file: For Claude Desktop Users.

2. Open the claude_desktop_config.json file in a text editor and add the following configuration:

{
  "mcpServers": {
    "onx-mcp-server": {
      "command": "npx",
      "args": ["-y", "@stevanfreeborn/onx-mcp-server"],
      "env": {
        "ONSPRING_API_KEY": "your_onspring_api_key",
        "ONSPRING_BASE_URL": "https://api.onspring.com"
      }
    }
  }
}

[!NOTE] The specific command and arguments may vary based on your setup.

Available Tools

The MCP Server exposes the following tools for AI assistants to interact with Onspring:

checkConnectionTool

Verifies that the server can connect to the Onspring API using the provided credentials.

getAppsTool

Retrieves a list of all accessible apps in the Onspring instance.

getFieldsTool

Gets all fields for a specified app.

Parameters:

• name: The name of the app

getRecordsTool

Retrieves records from an app with specified fields.

Parameters:

• appName: The name of the app
• fields: Array of field names to retrieve
• pageNumber: The page number to start from (1-based)
• numberOfPages: The number of pages to retrieve

getReportsTool

Gets all reports available for a specified app.

Parameters:

• appName: The name of the app

getReportDataTool

Retrieves data from a specified report.

Parameters:

• appName: The name of the app
• reportName: The name of the report
• dataType: The type of report data to retrieve (optional)

queryRecordsTool

Queries records from an app using a filter.

Parameters:

• appName: The name of the app
• fields: Array of field names to retrieve
• filter: A filter object to restrict the results
• pageNumber: The page number to start from (1-based)
• numberOfPages: The number of pages to retrieve

getFileTool

Retrieves a file stored in an attachment field.

Parameters:

• appName: The name of the app
• fieldName: The name of the attachment field
• recordId: The ID of the record containing the file
• fileName: The name of the file to retrieve

Development

Setup Development Environment

# Install dependencies
npm install

# Run in development mode (watches for changes)
npm run dev

Testing

The project uses Vitest for testing:

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests with UI
npm run test:ui

Inspecting the Server

You can use the MCP Inspector to test the server:

npm run inspect

License

This project is licensed under the MIT License - see the LICENSE.md file for details.