@iflow-mcp/graphlit-graphlit-mcp-server 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Unstruk Data Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,371 @@
+[![npm version](https://badge.fury.io/js/graphlit-mcp-server.svg)](https://badge.fury.io/js/graphlit-mcp-server)
+[![smithery badge](https://smithery.ai/badge/@graphlit/graphlit-mcp-server)](https://smithery.ai/server/@graphlit/graphlit-mcp-server)
+
+# Model Context Protocol (MCP) Server for Graphlit Platform
+
+## Overview
+
+The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. This document outlines the setup process and provides a basic example of using the client.
+
+Ingest anything from Slack, Discord, websites, Google Drive, email, Jira, Linear or GitHub into a Graphlit project - and then search and retrieve relevant knowledge within an MCP client like Cursor, Windsurf, Goose or Cline.
+
+Your Graphlit project acts as a searchable, and RAG-ready knowledge base across all your developer and product management tools.
+
+Documents (PDF, DOCX, PPTX, etc.) and HTML web pages will be extracted to Markdown upon ingestion. Audio and video files will be transcribed upon ingestion.
+
+Web crawling and web search are built-in as MCP tools, with no need to integrate other tools like Firecrawl, Exa, etc. separately.
+
+You can read more about the MCP Server use cases and features on our [blog](https://www.graphlit.com/blog/graphlit-mcp-server).
+
+Watch our latest [YouTube video](https://www.youtube.com/watch?v=Or-QqonvcAs&t=4s) on using the Graphlit MCP Server with the Goose MCP client.
+
+For any questions on using the MCP Server, please join our [Discord](https://discord.gg/ygFmfjy3Qx) community and post on the #mcp channel.
+
+<a href="https://glama.ai/mcp/servers/fscrivteod">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/fscrivteod/badge" alt="graphlit-mcp-server MCP server" />
+</a>
+
+## Tools
+
+### Retrieval
+
+- Query Contents
+- Query Collections
+- Query Feeds
+- Query Conversations
+- Retrieve Relevant Sources
+- Retrieve Similar Images
+- Visually Describe Image
+
+### RAG
+
+- Prompt LLM Conversation
+
+### Extraction
+
+- Extract Structured JSON from Text
+
+### Publishing
+
+- Publish as Audio (ElevenLabs Audio)
+- Publish as Image (OpenAI Image Generation)
+
+### Ingestion
+
+- Files
+- Web Pages
+- Messages
+- Posts
+- Emails
+- Issues
+- Text
+- Memory (Short-Term)
+
+### Data Connectors
+
+- Microsoft Outlook email
+- Google Mail
+- Notion
+- Reddit
+- Linear
+- Jira
+- GitHub Issues
+- Google Drive
+- OneDrive
+- SharePoint
+- Dropbox
+- Box
+- GitHub
+- Slack
+- Microsoft Teams
+- Discord
+- Twitter/X
+- Podcasts (RSS)
+
+### Web
+
+- Web Crawling
+- Web Search (including Podcast Search)
+- Web Mapping
+- Screenshot Page
+
+### Notifications
+
+- Slack
+- Email
+- Webhook
+- Twitter/X
+
+### Operations
+
+- Configure Project
+- Create Collection
+- Add Contents to Collection
+- Remove Contents from Collection
+- Delete Collection(s)
+- Delete Feed(s)
+- Delete Content(s)
+- Delete Conversation(s)
+- Is Feed Done?
+- Is Content Done?
+
+### Enumerations
+
+- List Slack Channels
+- List Microsoft Teams Teams
+- List Microsoft Teams Channels
+- List SharePoint Libraries
+- List SharePoint Folders
+- List Linear Projects
+- List Notion Databases
+- List Notion Pages
+- List Dropbox Folders
+- List Box Folders
+- List Discord Guilds
+- List Discord Channels
+- List Google Calendars
+- List Microsoft Calendars
+
+## Resources
+
+- Project
+- Contents
+- Feeds
+- Collections (of Content)
+- Workflows
+- Conversations
+- Specifications
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+- Node.js installed on your system (recommended version 18.x or higher).
+- An active account on the [Graphlit Platform](https://portal.graphlit.dev) with access to the API settings dashboard.
+
+## Configuration
+
+The Graphlit MCP Server supports environment variables to be set for authentication and configuration:
+
+- `GRAPHLIT_ENVIRONMENT_ID`: Your environment ID.
+- `GRAPHLIT_ORGANIZATION_ID`: Your organization ID.
+- `GRAPHLIT_JWT_SECRET`: Your JWT secret for signing the JWT token.
+
+You can find these values in the API settings dashboard on the [Graphlit Platform](https://portal.graphlit.dev).
+
+## Installation
+
+### Installing via VS Code
+
+For quick installation, use one of the one-click install buttons below:
+
+[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=graphlit&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22organization_id%22%2C%22description%22%3A%22Graphlit%20Organization%20ID%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22environment_id%22%2C%22description%22%3A%22Graphlit%20Environment%20ID%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22jwt_secret%22%2C%22description%22%3A%22Graphlit%20JWT%20Secret%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22graphlit-mcp-server%22%5D%2C%22env%22%3A%7B%22GRAPHLIT_ORGANIZATION_ID%22%3A%22%24%7Binput%3Aorganization_id%7D%22%2C%22GRAPHLIT_ENVIRONMENT_ID%22%3A%22%24%7Binput%3Aenvironment_id%7D%22%2C%22GRAPHLIT_JWT_SECRET%22%3A%22%24%7Binput%3Ajwt_secret%7D%22%7D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=graphlit&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22organization_id%22%2C%22description%22%3A%22Graphlit%20Organization%20ID%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22environment_id%22%2C%22description%22%3A%22Graphlit%20Environment%20ID%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22jwt_secret%22%2C%22description%22%3A%22Graphlit%20JWT%20Secret%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22graphlit-mcp-server%22%5D%2C%22env%22%3A%7B%22GRAPHLIT_ORGANIZATION_ID%22%3A%22%24%7Binput%3Aorganization_id%7D%22%2C%22GRAPHLIT_ENVIRONMENT_ID%22%3A%22%24%7Binput%3Aenvironment_id%7D%22%2C%22GRAPHLIT_JWT_SECRET%22%3A%22%24%7Binput%3Ajwt_secret%7D%22%7D%7D&quality=insiders)
+
+For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
+
+Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
+
+> Note that the `mcp` key is not needed in the `.vscode/mcp.json` file.
+
+```json
+{
+  "mcp": {
+    "inputs": [
+      {
+        "type": "promptString",
+        "id": "organization_id",
+        "description": "Graphlit Organization ID",
+        "password": true
+      },
+      {
+        "type": "promptString",
+        "id": "environment_id",
+        "description": "Graphlit Environment ID",
+        "password": true
+      },
+      {
+        "type": "promptString",
+        "id": "jwt_secret",
+        "description": "Graphlit JWT Secret",
+        "password": true
+      }
+    ],
+    "servers": {
+      "graphlit": {
+        "command": "npx",
+        "args": ["-y", "graphlit-mcp-server"],
+        "env": {
+          "GRAPHLIT_ORGANIZATION_ID": "${input:organization_id}",
+          "GRAPHLIT_ENVIRONMENT_ID": "${input:environment_id}",
+          "GRAPHLIT_JWT_SECRET": "${input:jwt_secret}"
+        }
+      }
+    }
+  }
+}
+```
+
+### Installing via Windsurf
+
+To install graphlit-mcp-server in Windsurf IDE application, Cline should use NPX:
+
+```bash
+npx -y graphlit-mcp-server
+```
+
+Your mcp_config.json file should be configured similar to:
+
+```
+{
+    "mcpServers": {
+        "graphlit-mcp-server": {
+            "command": "npx",
+            "args": [
+                "-y",
+                "graphlit-mcp-server"
+            ],
+            "env": {
+                "GRAPHLIT_ORGANIZATION_ID": "your-organization-id",
+                "GRAPHLIT_ENVIRONMENT_ID": "your-environment-id",
+                "GRAPHLIT_JWT_SECRET": "your-jwt-secret",
+            }
+        }
+    }
+}
+```
+
+### Installing via Cline
+
+To install graphlit-mcp-server in Cline IDE application, Cline should use NPX:
+
+```bash
+npx -y graphlit-mcp-server
+```
+
+Your cline_mcp_settings.json file should be configured similar to:
+
+```
+{
+    "mcpServers": {
+        "graphlit-mcp-server": {
+            "command": "npx",
+            "args": [
+                "-y",
+                "graphlit-mcp-server"
+            ],
+            "env": {
+                "GRAPHLIT_ORGANIZATION_ID": "your-organization-id",
+                "GRAPHLIT_ENVIRONMENT_ID": "your-environment-id",
+                "GRAPHLIT_JWT_SECRET": "your-jwt-secret",
+            }
+        }
+    }
+}
+```
+
+### Installing via Cursor
+
+To install graphlit-mcp-server in Cursor IDE application, Cursor should use NPX:
+
+```bash
+npx -y graphlit-mcp-server
+```
+
+Your mcp.json file should be configured similar to:
+
+```
+{
+    "mcpServers": {
+        "graphlit-mcp-server": {
+            "command": "npx",
+            "args": [
+                "-y",
+                "graphlit-mcp-server"
+            ],
+            "env": {
+                "GRAPHLIT_ORGANIZATION_ID": "your-organization-id",
+                "GRAPHLIT_ENVIRONMENT_ID": "your-environment-id",
+                "GRAPHLIT_JWT_SECRET": "your-jwt-secret",
+            }
+        }
+    }
+}
+```
+
+### Installing via Smithery
+
+To install graphlit-mcp-server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@graphlit/graphlit-mcp-server):
+
+```bash
+npx -y @smithery/cli install @graphlit/graphlit-mcp-server --client claude
+```
+
+### Installing manually
+
+To use the Graphlit MCP Server in any MCP client application, use:
+
+```
+{
+    "mcpServers": {
+        "graphlit-mcp-server": {
+            "command": "npx",
+            "args": [
+                "-y",
+                "graphlit-mcp-server"
+            ],
+            "env": {
+                "GRAPHLIT_ORGANIZATION_ID": "your-organization-id",
+                "GRAPHLIT_ENVIRONMENT_ID": "your-environment-id",
+                "GRAPHLIT_JWT_SECRET": "your-jwt-secret",
+            }
+        }
+    }
+}
+```
+
+Optionally, you can configure the credentials for data connectors, such as Slack, Google Email and Notion.
+Only GRAPHLIT_ORGANIZATION_ID, GRAPHLIT_ENVIRONMENT_ID and GRAPHLIT_JWT_SECRET are required.
+
+```
+{
+    "mcpServers": {
+        "graphlit-mcp-server": {
+            "command": "npx",
+            "args": [
+                "-y",
+                "graphlit-mcp-server"
+            ],
+            "env": {
+                "GRAPHLIT_ORGANIZATION_ID": "your-organization-id",
+                "GRAPHLIT_ENVIRONMENT_ID": "your-environment-id",
+                "GRAPHLIT_JWT_SECRET": "your-jwt-secret",
+                "SLACK_BOT_TOKEN": "your-slack-bot-token",
+                "DISCORD_BOT_TOKEN": "your-discord-bot-token",
+                "TWITTER_TOKEN": "your-twitter-token",
+                "GOOGLE_EMAIL_REFRESH_TOKEN": "your-google-refresh-token",
+                "GOOGLE_EMAIL_CLIENT_ID": "your-google-client-id",
+                "GOOGLE_EMAIL_CLIENT_SECRET": "your-google-client-secret",
+                "LINEAR_API_KEY": "your-linear-api-key",
+                "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-pat",
+                "JIRA_EMAIL": "your-jira-email",
+                "JIRA_TOKEN": "your-jira-token",
+                "NOTION_API_KEY": "your-notion-api-key"
+            }
+        }
+    }
+}
+```
+
+NOTE: when running 'npx' on Windows, you may need to explicitly call npx via the command prompt.
+
+```
+"command": "C:\\Windows\\System32\\cmd.exe /c npx"
+```
+
+## Support
+
+Please refer to the [Graphlit API Documentation](https://docs.graphlit.dev/).
+
+For support with the Graphlit MCP Server, please submit a [GitHub Issue](https://github.com/graphlit/graphlit-mcp-server/issues).
+
+For further support with the Graphlit Platform, please join our [Discord](https://discord.gg/ygFmfjy3Qx) community.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const server: McpServer;

package/dist/index.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerResources } from "./resources.js";
+import { registerTools } from "./tools.js";
+const DEFAULT_INSTRUCTIONS = `
+You are provided a set of MCP tools and resources that integrate with the [Graphlit](https://www.graphlit.com) Platform.
+
+To use each of the Graphlit MCP tools, there may be environment variables which are required to be configured in your MCP client. These are described in the description for each tool.
+These must be configured in the MCP client YAML or JSON configuration file before you can use the tools. *Do not* set these directly in your Terminal or shell environment.
+
+Graphlit is an LLM-enabled knowledge API platform, which supports these resources:
+- project: container for ingested contents, which can be configured with a default workflow
+- contents: all ingested files, web pages, messages, etc.; also includes short-term 'memory' contents
+- feeds: data connectors which ingest contents
+- collections: named groups of contents
+- conversations: chat message history of LLM conversation, which uses RAG pipeline for content retrieval
+- workflows: how content is handled during the ingestion process
+- specifications: LLM configuration presets, used by workflows and conversations
+
+Identifiers for all resources are unique within the Graphlit project, and are formatted as GUIDs.
+
+You have access to one and only one Graphlit project, which can optionally be configured with a workflow to guide the document preparation and entity extraction of ingested content. 
+The Graphlit project is non-deletable, but you can create and delete contents, feeds, collections, conversations, specifications and workflows within the project.
+
+You can query the Graphlit project resource for the credits used, LLM tokens used, and the available project quota. By default, credits cost USD$0.10, and are discounted on higher paid tiers.
+
+With this Graphlit MCP Server, you can ingest anything from Slack, Discord, websites, Notion, Google Drive, email, Jira, Linear or GitHub into a Graphlit project - and then search and retrieve relevant knowledge within an MCP client like Cursor, Windsurf or Cline.
+
+Documents (PDF, DOCX, PPTX, etc.) and HTML web pages will be extracted to Markdown upon ingestion. Audio and video files will be transcribed upon ingestion.
+
+## Best Practices:
+1. Always look for matching resources before you try to call any tools.
+For example, "have i configured any graphlit workflows?", you should check for workflow resources before trying to call any other tools.
+2. Don't use 'retrieveSources' to locate contents, when you have already added the contents into a collection. In that case, first retrieve the collection resource, which contains the content resources.
+3. Only call the 'configureProject' tool when the user explicitly asks to configure their Graphlit project defaults.
+4. Never infer, guess at or hallucinate any URLs. Always retrieve the latest content resources in order to get downloadable URLs.
+5. Use 'ingestMemory' to save short-term memories, such as temporary notes or intermediate state for research. Use 'ingestText' to store long-term knowledge, such as Markdown results from research.
+6. Always use 'PODSCAN' web search type when searching for podcast episodes, podcast appearances, etc.
+7. Prioritize using feeds, rather than 'ingestUrl', when you want to ingest a website. Feeds are more efficient and faster than using 'ingestUrl'.
+If you receive a request to ingest a GitHub URL, use the 'ingestGitHubFiles' tool to ingest the repository, rather than using 'ingestUrl'.
+Always attempt to use the most-specific tool for the task at hand.
+
+## Short-term vs Long-term Memory:
+You can perform scatter-gather operations where you save short-term memories after each workflow step, and then gather relevant memories prior to the moving onto the next step. 
+Leverage short-term memories when evaluating the results of a workflow step, and then use long-term memories to store the final results of your workflow.
+You can collect memories in collections, and then use the 'queryContents' tool to retrieve the 'memory' contents by the collection. This will help you to keep track of your progress and avoid losing any important information.
+
+If you have any trouble with this Graphlit MCP Server, join our [Discord](https://discord.gg/ygFmfjy3Qx) community for support.
+`;
+export const server = new McpServer({
+    name: "Graphlit MCP Server",
+    version: "1.0.0",
+}, {
+    instructions: DEFAULT_INSTRUCTIONS,
+});
+registerResources(server);
+registerTools(server);
+async function runServer() {
+    try {
+        console.error("Attempting to start Graphlit MCP Server.");
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error("Successfully started Graphlit MCP Server.");
+    }
+    catch (error) {
+        console.error("Failed to start Graphlit MCP Server.", error);
+        process.exit(1);
+    }
+}
+runServer().catch((error) => {
+    console.error("Failed to start Graphlit MCP Server.", error);
+    process.exit(1);
+});

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;