@neverinfamous/mysql-mcp 2.1.0

package/src/adapters/mysql/tools/spatial/__tests__/operations.test.ts

@@ -0,0 +1,164 @@
+/**
+ * mysql-mcp - Spatial Operations Tools Unit Tests
+ * 
+ * Comprehensive tests for operations.ts module functions.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+    createSpatialIntersectionTool,
+    createSpatialBufferTool,
+    createSpatialTransformTool,
+    createSpatialGeoJSONTool
+} from '../operations.js';
+import type { MySQLAdapter } from '../../../MySQLAdapter.js';
+import { createMockMySQLAdapter, createMockRequestContext, createMockQueryResult } from '../../../../../__tests__/mocks/index.js';
+
+describe('Spatial Operations Tools', () => {
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        mockContext = createMockRequestContext();
+    });
+
+    describe('createSpatialIntersectionTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialIntersectionTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_intersection');
+        });
+
+        it('should calculate intersection', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                intersects: 1,
+                intersection_wkt: 'POINT(5 5)',
+                intersection_geojson: '{"type":"Point"}'
+            }]));
+
+            const tool = createSpatialIntersectionTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                geometry1: 'POLYGON(...)',
+                geometry2: 'POINT(5 5)'
+            }, mockContext) as { intersects: boolean; intersectionWkt: string };
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            expect(result.intersects).toBe(true);
+            expect(result.intersectionWkt).toBe('POINT(5 5)');
+        });
+
+        it('should handle no intersection', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                intersects: 0
+            }]));
+
+            const tool = createSpatialIntersectionTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                geometry1: 'POLYGON(...)',
+                geometry2: 'POINT(100 100)'
+            }, mockContext) as { intersects: boolean };
+
+            expect(result.intersects).toBe(false);
+        });
+    });
+
+    describe('createSpatialBufferTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialBufferTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_buffer');
+        });
+
+        it('should create buffer around geometry', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                buffer_wkt: 'POLYGON(...)',
+                buffer_geojson: '{"type":"Polygon"}'
+            }]));
+
+            const tool = createSpatialBufferTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                geometry: 'POINT(0 0)',
+                distance: 10
+            }, mockContext);
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            expect(result).toHaveProperty('bufferWkt');
+            expect(result).toHaveProperty('bufferGeoJson');
+        });
+    });
+
+    describe('createSpatialTransformTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialTransformTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_transform');
+        });
+
+        it('should transform geometry between SRIDs', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                transformed_wkt: 'POINT(1000 2000)',
+                transformed_geojson: '{"type":"Point"}'
+            }]));
+
+            const tool = createSpatialTransformTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                geometry: 'POINT(10 20)',
+                fromSrid: 4326,
+                toSrid: 3857
+            }, mockContext);
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_Transform');
+            expect(call).toContain('4326');
+            expect(call).toContain('3857');
+            expect(result).toHaveProperty('transformedWkt');
+        });
+    });
+
+    describe('createSpatialGeoJSONTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialGeoJSONTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_geojson');
+        });
+
+        it('should convert WKT to GeoJSON', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                geoJson: '{"type":"Point","coordinates":[10,20]}'
+            }]));
+
+            const tool = createSpatialGeoJSONTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ geometry: 'POINT(10 20)' }, mockContext) as { geoJson: any };
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            expect(result.geoJson).toEqual({ type: 'Point', coordinates: [10, 20] });
+        });
+
+        it('should convert GeoJSON to WKT', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                wkt: 'POINT(10 20)'
+            }]));
+
+            const tool = createSpatialGeoJSONTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({ geoJson: '{"type":"Point","coordinates":[10,20]}' }, mockContext) as { wkt: string };
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            expect(result.wkt).toBe('POINT(10 20)');
+        });
+
+        it('should throw if neither geometry nor geoJson provided', async () => {
+            const tool = createSpatialGeoJSONTool(mockAdapter as unknown as MySQLAdapter);
+            // Use type assertion or casting to bypass TS error for invalid input in test
+            // Zod parser will catch it, or refiner.
+            // Wait, Zod schema has refine check.
+            await expect(tool.handler({}, mockContext)).rejects.toThrow();
+        });
+
+        it('should throw if both geometry and geoJson provided', async () => {
+            const tool = createSpatialGeoJSONTool(mockAdapter as unknown as MySQLAdapter);
+            await expect(tool.handler({
+                geometry: 'POINT(0 0)',
+                geoJson: '{}'
+            }, mockContext)).rejects.toThrow();
+        });
+    });
+});

package/src/adapters/mysql/tools/spatial/__tests__/queries.test.ts

@@ -0,0 +1,253 @@
+
+/**
+ * mysql-mcp - Spatial Queries Tools Unit Tests
+ * 
+ * Comprehensive tests for queries.ts module functions.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+    createSpatialDistanceTool,
+    createSpatialDistanceSphereTool,
+    createSpatialContainsTool,
+    createSpatialWithinTool
+} from '../queries.js';
+import type { MySQLAdapter } from '../../../MySQLAdapter.js';
+import { createMockMySQLAdapter, createMockRequestContext, createMockQueryResult } from '../../../../../__tests__/mocks/index.js';
+
+describe('Spatial Queries Tools', () => {
+    let mockAdapter: ReturnType<typeof createMockMySQLAdapter>;
+    let mockContext: ReturnType<typeof createMockRequestContext>;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockAdapter = createMockMySQLAdapter();
+        mockContext = createMockRequestContext();
+    });
+
+    describe('createSpatialDistanceTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialDistanceTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_distance');
+        });
+
+        it('should query distance with defaults', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([{
+                id: 1,
+                distance: 100
+            }]));
+
+            const tool = createSpatialDistanceTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                table: 'locations',
+                spatialColumn: 'geom',
+                point: { longitude: 0, latitude: 0 }
+            }, mockContext) as { results: unknown[] };
+
+            expect(mockAdapter.executeQuery).toHaveBeenCalled();
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_Distance');
+            // Check SRID default with axis-order option
+            expect(call).toContain("ST_GeomFromText(?, 4326, 'axis-order=long-lat')");
+            expect(result.results).toHaveLength(1);
+        });
+
+        it('should filter by maxDistance and use custom SRID', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialDistanceTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({
+                table: 'locations',
+                spatialColumn: 'geom',
+                point: { longitude: 0, latitude: 0 },
+                maxDistance: 500,
+                srid: 3857,
+                limit: 5
+            }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_Distance');
+            expect(call).toContain('<= ?');
+            expect(call).toContain("ST_GeomFromText(?, 3857, 'axis-order=long-lat')");
+            expect(call).toContain('LIMIT 5');
+            const args = mockAdapter.executeQuery.mock.calls[0][1] as any[];
+            expect(args).toContain(500);
+        });
+
+        it('should validate table name', async () => {
+            const tool = createSpatialDistanceTool(mockAdapter as unknown as MySQLAdapter);
+            await expect(tool.handler({
+                table: 'invalid; drop table',
+                spatialColumn: 'geom',
+                point: { longitude: 0, latitude: 0 }
+            }, mockContext)).rejects.toThrow('Invalid table name');
+        });
+
+        it('should validate column name', async () => {
+            const tool = createSpatialDistanceTool(mockAdapter as unknown as MySQLAdapter);
+            await expect(tool.handler({
+                table: 'valid_table',
+                spatialColumn: 'invalid column',
+                point: { longitude: 0, latitude: 0 }
+            }, mockContext)).rejects.toThrow('Invalid column name');
+        });
+
+        it('should handle undefined rows result', async () => {
+            // Mock executeQuery returning no rows property potentially, or null rows
+            mockAdapter.executeQuery.mockResolvedValue({
+                fields: [],
+                rows: null
+            } as any);
+
+            const tool = createSpatialDistanceTool(mockAdapter as unknown as MySQLAdapter);
+            const result = await tool.handler({
+                table: 'locations',
+                spatialColumn: 'geom',
+                point: { longitude: 0, latitude: 0 }
+            }, mockContext) as any;
+
+            expect(result.results).toEqual([]);
+            expect(result.count).toBe(0);
+        });
+    });
+
+    describe('createSpatialDistanceSphereTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialDistanceSphereTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_distance_sphere');
+        });
+
+        it('should query spherical distance', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialDistanceSphereTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({
+                table: 'locations',
+                spatialColumn: 'geom',
+                point: { longitude: 0, latitude: 0 }
+            }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_Distance_Sphere');
+        });
+
+        it('should support optional maxDistance', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialDistanceSphereTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({
+                table: 'locations',
+                spatialColumn: 'geom',
+                point: { longitude: 0, latitude: 0 },
+                maxDistance: 1000
+            }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('<= ?');
+        });
+
+        it('should validate identifiers', async () => {
+            const tool = createSpatialDistanceSphereTool(mockAdapter as unknown as MySQLAdapter);
+            await expect(tool.handler({
+                table: 'invalid',
+                spatialColumn: 'bad-column', // Hyphens not allowed by simple regex maybe? 
+                // Regex is /^[a-zA-Z_][a-zA-Z0-9_]*$/ so hyphen is invalid
+                point: { longitude: 0, latitude: 0 }
+            }, mockContext)).rejects.toThrow('Invalid column name');
+        });
+    });
+
+    describe('createSpatialContainsTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialContainsTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_contains');
+        });
+
+        it('should query for contained geometries with default SRID', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialContainsTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({
+                table: 'parcels',
+                spatialColumn: 'boundary',
+                polygon: 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))'
+            }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_Contains');
+            // Verify SRID is applied with default 4326
+            expect(call).toContain('ST_GeomFromText(?, 4326)');
+        });
+
+        it('should support custom SRID for contains query', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialContainsTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({
+                table: 'parcels',
+                spatialColumn: 'boundary',
+                polygon: 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))',
+                srid: 3857
+            }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_GeomFromText(?, 3857)');
+        });
+
+        it('should validate identifiers', async () => {
+            const tool = createSpatialContainsTool(mockAdapter as unknown as MySQLAdapter);
+            await expect(tool.handler({
+                table: 'bad-table',
+                spatialColumn: 'boundary',
+                polygon: 'P'
+            }, mockContext)).rejects.toThrow('Invalid table name');
+        });
+    });
+
+    describe('createSpatialWithinTool', () => {
+        it('should create tool with correct definition', () => {
+            const tool = createSpatialWithinTool(mockAdapter as unknown as MySQLAdapter);
+            expect(tool.name).toBe('mysql_spatial_within');
+        });
+
+        it('should query for geometries within shape with default SRID', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialWithinTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({
+                table: 'landmarks',
+                spatialColumn: 'location',
+                geometry: 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))'
+            }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_Within');
+            // Verify SRID is applied with default 4326
+            expect(call).toContain('ST_GeomFromText(?, 4326)');
+        });
+
+        it('should support custom SRID for within query', async () => {
+            mockAdapter.executeQuery.mockResolvedValue(createMockQueryResult([]));
+
+            const tool = createSpatialWithinTool(mockAdapter as unknown as MySQLAdapter);
+            await tool.handler({
+                table: 'landmarks',
+                spatialColumn: 'location',
+                geometry: 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))',
+                srid: 3857
+            }, mockContext);
+
+            const call = mockAdapter.executeQuery.mock.calls[0][0] as string;
+            expect(call).toContain('ST_GeomFromText(?, 3857)');
+        });
+
+        it('should validate identifiers', async () => {
+            const tool = createSpatialWithinTool(mockAdapter as unknown as MySQLAdapter);
+            await expect(tool.handler({
+                table: 't',
+                spatialColumn: 'bad col',
+                geometry: 'P'
+            }, mockContext)).rejects.toThrow('Invalid column name');
+        });
+    });
+});

package/src/adapters/mysql/tools/spatial/geometry.ts

@@ -0,0 +1,106 @@
+/**
+ * MySQL Spatial/GIS Tools - Geometry Creation
+ * 
+ * Tools for creating basic geometry objects.
+ * 2 tools: point and polygon creation.
+ */
+
+import { z } from 'zod';
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+import type { ToolDefinition, RequestContext } from '../../../../types/index.js';
+
+// =============================================================================
+// Zod Schemas
+// =============================================================================
+
+const PointSchema = z.object({
+    longitude: z.number().describe('Longitude coordinate'),
+    latitude: z.number().describe('Latitude coordinate'),
+    srid: z.number().default(4326).describe('SRID')
+});
+
+const PolygonSchema = z.object({
+    coordinates: z.array(z.array(z.array(z.number()).min(2).max(2))).describe('Polygon coordinates as array of rings, each ring is array of [lon, lat] pairs'),
+    srid: z.number().default(4326).describe('SRID')
+});
+
+/**
+ * Create a POINT geometry
+ */
+export function createSpatialPointTool(adapter: MySQLAdapter): ToolDefinition {
+    return {
+        name: 'mysql_spatial_point',
+        title: 'MySQL Create Point',
+        description: 'Create a POINT geometry from longitude/latitude coordinates.',
+        group: 'spatial',
+        inputSchema: PointSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { longitude, latitude, srid } = PointSchema.parse(params);
+
+            // Use 'axis-order=long-lat' to accept natural longitude-latitude order
+            // MySQL 8.0+ defaults to EPSG standard (latitude-longitude) for SRID 4326
+            const result = await adapter.executeQuery(
+                `SELECT ST_AsText(ST_SRID(ST_GeomFromText('POINT(${String(longitude)} ${String(latitude)})', ${String(srid)}, 'axis-order=long-lat'), ${String(srid)})) as wkt,
+                        ST_AsGeoJSON(ST_SRID(ST_GeomFromText('POINT(${String(longitude)} ${String(latitude)})', ${String(srid)}, 'axis-order=long-lat'), ${String(srid)})) as geoJson`
+            );
+
+            const row = result.rows?.[0];
+            const geoJsonStr = row?.['geoJson'];
+            return {
+                wkt: row?.['wkt'],
+                geoJson: typeof geoJsonStr === 'string' ? JSON.parse(geoJsonStr) as Record<string, unknown> : null,
+                srid,
+                longitude,
+                latitude
+            };
+        }
+    };
+}
+
+/**
+ * Create a POLYGON geometry
+ */
+export function createSpatialPolygonTool(adapter: MySQLAdapter): ToolDefinition {
+    return {
+        name: 'mysql_spatial_polygon',
+        title: 'MySQL Create Polygon',
+        description: 'Create a POLYGON geometry from coordinates.',
+        group: 'spatial',
+        inputSchema: PolygonSchema,
+        requiredScopes: ['read'],
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true
+        },
+        handler: async (params: unknown, _context: RequestContext) => {
+            const { coordinates, srid } = PolygonSchema.parse(params);
+
+            // Build WKT polygon
+            const rings = coordinates.map(ring =>
+                '(' + ring.map(([lon, lat]) => `${String(lon)} ${String(lat)}`).join(', ') + ')'
+            );
+            const wkt = `POLYGON(${rings.join(', ')})`;
+
+            const result = await adapter.executeQuery(
+                `SELECT ST_AsText(ST_SRID(ST_GeomFromText(?), ${String(srid)})) as wkt,
+                        ST_AsGeoJSON(ST_SRID(ST_GeomFromText(?), ${String(srid)})) as geoJson,
+                        ST_Area(ST_SRID(ST_GeomFromText(?), ${String(srid)})) as area`,
+                [wkt, wkt, wkt]
+            );
+
+            const row = result.rows?.[0];
+            const geoJsonStr = row?.['geoJson'];
+            return {
+                wkt: row?.['wkt'],
+                geoJson: typeof geoJsonStr === 'string' ? JSON.parse(geoJsonStr) as Record<string, unknown> : null,
+                area: row?.['area'],
+                srid
+            };
+        }
+    };
+}

package/src/adapters/mysql/tools/spatial/index.ts

@@ -0,0 +1,54 @@
+/**
+ * MySQL Spatial/GIS Tools
+ * 
+ * Tools for geospatial data operations in MySQL 8.0+.
+ * 12 tools total (2 setup + 2 geometry + 4 queries + 4 operations).
+ */
+
+import type { MySQLAdapter } from '../../MySQLAdapter.js';
+import type { ToolDefinition } from '../../../../types/index.js';
+
+// Import from submodules
+import {
+    createSpatialCreateColumnTool,
+    createSpatialCreateIndexTool
+} from './setup.js';
+
+import {
+    createSpatialPointTool,
+    createSpatialPolygonTool
+} from './geometry.js';
+
+import {
+    createSpatialDistanceTool,
+    createSpatialDistanceSphereTool,
+    createSpatialContainsTool,
+    createSpatialWithinTool
+} from './queries.js';
+
+import {
+    createSpatialIntersectionTool,
+    createSpatialBufferTool,
+    createSpatialTransformTool,
+    createSpatialGeoJSONTool
+} from './operations.js';
+
+/**
+ * Get all spatial tools
+ */
+export function getSpatialTools(adapter: MySQLAdapter): ToolDefinition[] {
+    return [
+        createSpatialCreateColumnTool(adapter),
+        createSpatialCreateIndexTool(adapter),
+        createSpatialPointTool(adapter),
+        createSpatialPolygonTool(adapter),
+        createSpatialDistanceTool(adapter),
+        createSpatialDistanceSphereTool(adapter),
+        createSpatialContainsTool(adapter),
+        createSpatialWithinTool(adapter),
+        createSpatialIntersectionTool(adapter),
+        createSpatialBufferTool(adapter),
+        createSpatialTransformTool(adapter),
+        createSpatialGeoJSONTool(adapter)
+    ];
+}