intuition

The Intuition MCP Server exposes a set of MCP tools that operate against the Intuition knowledge graph over an HTTP stream. It provides endpoints to extract structured triples from natural language, search for atoms (accounts, concepts, and entities), fetch account information, and explore relationships such as who an account follows or who follows an account. Tools are accessed via the MCP SDK using either the Streamable HTTP transport (recommended) or the legacy Server-Sent Events transport. By default, you should connect to the /mcp endpoint for streamable requests, with /sse available for SSE compatibility during migration. The tools return results enriched with atom IDs and connection details, and responses are sorted by relevance or position as described in each tool’s input schema. The available tools include: extract_triples, search_atoms, get_account_info, search_lists, get_following, get_followers, and search_account_ids. You can compose requests following each tool’s input schema to retrieve at least a handful of relevant results for downstream applications.

Prerequisites: Node.js 14+ and pnpm installed globally. Optional: Docker if you prefer containerized execution.

Install from source:

# Clone the repository
git clone <repository-url>
cd intuition-mcp-server

# Install using pnpm (preferred for this project)
pnpm install

Run the server (HTTP stream endpoint recommended):

# Start the server (HTTP transport)
pnpm run start:http

If you prefer building first (TypeScript project):

# Install and build
pnpm install
pnpm run build

# Then start
pnpm run start:http

Environment and configuration:

• Ensure Node.js version is 14 or higher.
• Configure host/port via environment variables if needed (HOST, PORT).
• The MCP API base URL is available via MCP_API_BASE when running behind proxies or gateways.

Alternatively, you can run a containerized instance (if a Docker image is provided):

# Example (adjust image name as needed)
docker run -i intuition-mcp-server:latest

Post-install verification:

# Verify endpoint availability
curl -sS http://localhost:3001/mcp -H "Accept: application/json" | jq

If you encounter issues, check logs for startup errors related to port binding, dependencies, or TypeScript compilation.

Notes and tips:

• The preferred endpoint for clients implementing MCP SDK is the /mcp streamable HTTP endpoint. The /sse endpoint is deprecated in favor of streamable HTTP.
• If you run behind a reverse proxy, ensure proper websockets/streaming support and set the MCP_API_BASE accordingly.
• Tool input schemas are strict; ensure required fields are present and adhere to the defined types.
• For large queries, consider paging or streaming results as supported by the MCP SDK to avoid timeouts.
• Environment variables can be used to customize host, port, and API base; provide sensible defaults in local development.
• If you need to regenerate TypeScript types or rebuild after code changes, run the build script and restart the server.