{"id":26920786,"url":"https://github.com/flowcore-io/mcp-flowcore-local-readmodel","last_synced_at":"2025-04-01T22:48:29.534Z","repository":{"id":284251390,"uuid":"951548219","full_name":"flowcore-io/mcp-flowcore-local-readmodel","owner":"flowcore-io","description":"A local in-memory read model that can be fed data from the Flowcore Platform","archived":false,"fork":false,"pushed_at":"2025-03-24T23:24:31.000Z","size":104,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T00:20:26.510Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flowcore-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-19T21:19:58.000Z","updated_at":"2025-03-24T23:24:16.000Z","dependencies_parsed_at":"2025-03-25T00:20:37.917Z","dependency_job_id":null,"html_url":"https://github.com/flowcore-io/mcp-flowcore-local-readmodel","commit_stats":null,"previous_names":["flowcore-io/mcp-flowcore-local-readmodel"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flowcore-io%2Fmcp-flowcore-local-readmodel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flowcore-io%2Fmcp-flowcore-local-readmodel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flowcore-io%2Fmcp-flowcore-local-readmodel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flowcore-io%2Fmcp-flowcore-local-readmodel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flowcore-io","download_url":"https://codeload.github.com/flowcore-io/mcp-flowcore-local-readmodel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246724801,"owners_count":20823544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-01T22:48:29.078Z","updated_at":"2025-04-01T22:48:29.522Z","avatar_url":"https://github.com/flowcore-io.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flowcore Local Read Model MCP\n\nThis MCP (Model Context Protocol) server allows you to create and manage local read models using DuckDB, fed with events from the Flowcore Platform. It provides a set of tools to initialize a database, create tables, project events, and query the resulting data.\n\n## Installation\n\n```bash\nnpm install @flowcore/local-read-model-mcp\n```\n\n## Usage\n\nTo use this MCP, you need to provide either a username or a Personal Access Token (PAT) for authentication with the Flowcore Platform.\n\n```bash\nnpx @flowcore/local-read-model-mcp --username \u003cyour-username\u003e\n# or\nnpx @flowcore/local-read-model-mcp --pat \u003cyour-pat\u003e\n```\n\n## Environment Variables\n\n| Variable | Type | Description | Default | Required |\n|----------|------|-------------|----------|----------|\n| USERNAME | string | Your Flowcore username | - | ✓ |\n| PAT | string | Your Flowcore Personal Access Token | - | ✓ |\n\n## Available Tools\n\n### 1. Database Management\n\n#### Initialize DuckDB\n\nInitializes a DuckDB database for the read model. You can choose between in-memory or file-based storage.\n\n```typescript\ninitialize_duckdb({\n    file: \"/path/to/database.db\" // Optional, uses in-memory if not provided\n})\n```\n\n#### Close DuckDB\n\nCloses the database connection and stops any active event stream projections.\n\n```typescript\nclose_duckdb()\n```\n\n### 2. Table Management\n\n#### Create Projection Table\n\nCreates a new table in the DuckDB database using SQL.\n\n```typescript\ncreate_projection_table({\n    createTableSQL: `\n        CREATE TABLE my_table (\n            id INTEGER PRIMARY KEY,\n            created_at TIMESTAMP NOT NULL,\n            amount DECIMAL(10,2),\n            status VARCHAR(50) DEFAULT 'pending'\n        );\n    `\n})\n```\n\n### 3. Event Projection\n\n#### Create Event Projector\n\nCreates and registers a JavaScript function that transforms Flowcore events into database records.\n\n```typescript\ncreate_event_projector({\n    name: \"my_projector\",\n    absoluteFilePath: \"/path/to/projector.cjs\"\n})\n```\n\nExample projector function (projector.cjs):\n\n```javascript\nfunction projectEvent(event) {\n    return {\n        id: event.id,\n        timestamp: new Date(event.timestamp).toISOString(),\n        amount: Number.parseFloat(event.amount).toFixed(2),\n        status: String(event.status).toLowerCase()\n    };\n}\n\nmodule.exports = projectEvent;\n```\n\n#### Start Event Stream Projection\n\nStarts streaming events from Flowcore and projecting them to the database.\n\n```typescript\nstart_event_stream_projection({\n    tenant: \"your-tenant\",\n    dataCore: \"your-datacore\",\n    flowTypeName: \"your-flow-type\",\n    eventTypeName: \"your-event-type\",\n    startDate: \"2024-01-01T00:00:00Z\",\n    endDate: \"2024-01-31T23:59:59Z\",\n    projectorName: \"my_projector\",\n    targetTable: \"my_table\",\n    maxParallelism: 100 // Optional, default is 100\n})\n```\n\n#### Stop Event Stream Projection\n\nStops a specific event stream projection.\n\n```typescript\nstop_event_stream_projection({\n    streamId: \"stream-123\"\n})\n```\n\n### 4. Querying and Monitoring\n\n#### Query Database\n\nExecute SQL queries on the DuckDB database.\n\n```typescript\nquery_database({\n    query: \"SELECT * FROM my_table WHERE status = 'pending' LIMIT 10;\"\n})\n```\n\n#### Get Stream Information\n\nGet information about a specific event stream projection.\n\n```typescript\nget_stream_info({\n    streamId: \"stream-123\"\n})\n```\n\n#### Get All Streams\n\nGet information about all active event stream projections.\n\n```typescript\nget_all_streams()\n```\n\n## Best Practices\n\n### Table Creation\n\n1. Use appropriate data types and formats:\n   - TIMESTAMP: ISO 8601 format (YYYY-MM-DD HH:MM:SS.SSS)\n   - DATE: ISO format (YYYY-MM-DD)\n   - TIME: 24-hour format (HH:MM:SS.SSS)\n   - DECIMAL/NUMERIC: Specify precision and scale\n   - VARCHAR: Always specify length limit\n\n2. Follow naming conventions:\n   - Use lowercase for table and column names\n   - Use snake_case naming convention\n   - Include appropriate indexes\n   - Consider partitioning for large tables\n\n### Event Projectors\n\n1. Handle data type conversions properly\n2. Implement error handling for malformed input\n3. Return null for unmappable fields\n4. Use pure functions without side effects\n5. Handle null/undefined values gracefully\n\n## Example Workflow\n\nHere's a complete example of setting up a local read model:\n\n```typescript\n// 1. Initialize the database\ninitialize_duckdb({ file: \"my_read_model.db\" })\n\n// 2. Create a table\ncreate_projection_table({\n    createTableSQL: `\n        CREATE TABLE events (\n            event_id VARCHAR(100) PRIMARY KEY,\n            timestamp TIMESTAMP NOT NULL,\n            type VARCHAR(50),\n            data JSON\n        );\n    `\n})\n\n// 3. Create and register a projector\ncreate_event_projector({\n    name: \"event_projector\",\n    absoluteFilePath: \"./projector.cjs\"\n})\n\n// 4. Start streaming events\nstart_event_stream_projection({\n    tenant: \"my-tenant\",\n    dataCore: \"my-datacore\",\n    flowTypeName: \"my-flow\",\n    eventTypeName: \"my-events\",\n    startDate: \"2024-01-01T00:00:00Z\",\n    endDate: \"2024-01-31T23:59:59Z\",\n    projectorName: \"event_projector\",\n    targetTable: \"events\"\n})\n\n// 5. Query the results\nquery_database({\n    query: \"SELECT * FROM events ORDER BY timestamp DESC LIMIT 10;\"\n})\n\n// 6. Close the database when done\nclose_duckdb()\n```\n\n## License\n\n[Add your license information here]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflowcore-io%2Fmcp-flowcore-local-readmodel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflowcore-io%2Fmcp-flowcore-local-readmodel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflowcore-io%2Fmcp-flowcore-local-readmodel/lists"}