imasparql

This MCP server adapts the IMAS Parquet SPARQL endpoint (imasparql) to MCP (Model Context Protocol) so MCP clients can interact with it either via stdio (for tools like Cursor) or via an HTTP server. The stdio mode exposes MCP commands such as search_entities, get_entity, get_entity_details, get_entity_relations, get_unit_members, and get_unit_members_by_name, enabling script-based querying and automation. The HTTP server mode provides a REST-like RPC interface at http://localhost:3000/mcp, with the same JSON-RPC methods, making it convenient to integrate with web services or other HTTP clients. To use the stdio workflow, register the server in your MCP client configuration by running the provided command (for example: node path/to/imasparql-mcp-server/mcp-stdio.js) or install it globally and reference the binary (imasparql-mcp). Tools available under the stdio/SDK integration include: search_entities (filter by name, brand, height, weight, etc.), get_entity (basic info), get_entity_details (detailed info), get_entity_relations (affiliations, units), get_unit_members (members of a unit), and get_unit_members_by_name (members of a unit identified by name). For HTTP usage, start the dev or production server (pnpm dev or pnpm start) and send JSON-RPC requests to the /mcp endpoint to perform the same operations.

Prerequisites:\n- Node.js (ES Modules) with npm or pnpm installed.\n- Basic familiarity with JSON-RPC and MCP workflows.\n\nInstallation steps:\n1) Install dependencies with pnpm (from the project root):\nbash\npnpm install\n\n2) For STDIO usage (Cursor or similar MCP clients): ensure you have the mcp-stdio.js entry file and run as described in the README. Example (local):\nbash\nnode path/to/imasparql-mcp-server/mcp-stdio.js\n\nIf you prefer a global install after building, you can install the project globally and reference the generated binary as shown in the README. Example (global install):\nbash\npnpm install -g .\n\nThen reference the CLI as:bash\nimasparql-mcp\n\n3) For HTTP server usage in development: start the server with pnpm:\nbash\npnpm dev\n\n4) For production deployment: start with:\nbash\npnpm start\n\n5) To verify, curl the HTTP endpoint:\nbash\ncurl -X POST http://localhost:3000/mcp \n -H "Content-Type: application/json" \n -d '{"jsonrpc": "2.0", "id": 1, "method": "search_entities", "params": {"q": "春香"}}'\n

Notes and tips:\n- This MCP server supports both stdio-based and HTTP-based interactions. Choose the mode that best fits your tooling.\n- For the stdio mode, you typically register the command in your MCP client configuration. Example: { "mcpServers": { "imasparql": { "command": "node", "args": ["path/to/imasparql-mcp-server/mcp-stdio.js"] } } }.\n- The HTTP endpoint is served at http://localhost:3000/mcp by default. You can adjust port/host via environment variables when configuring your deployment.\n- Available MCP methods include: search_entities, get_entity, get_entity_details, get_entity_relations, get_unit_members, get_unit_members_by_name.\n- The backend depends on the imasparql SPARQL endpoint; network access to the endpoint URL (https://sparql.crssnky.xyz/spql/imas/query) is required for upstream data.\n- If you encounter CORS or network issues, verify the SPARQL endpoint accessibility and ensure the MCP server has network access in the deployment environment.