qmcp 0.1.0__tar.gz

qmcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gabi Teodoru
+
+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.

qmcp-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: qmcp
+Version: 0.1.0
+Summary: MCP Server for q/kdb+ integration
+Author-email: Gabi Teodoru <gabiteodoru@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/gabiteodoru/qmcp
+Project-URL: Bug Tracker, https://github.com/gabiteodoru/qmcp/issues
+Project-URL: Source Code, https://github.com/gabiteodoru/qmcp
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: numpy>=1.8.0
+Requires-Dist: pandas
+Requires-Dist: more_itertools
+Dynamic: license-file
+
+# qmcp Server
+
+A Model Context Protocol server for q/kdb+ integration.
+
+## Features
+
+- Connect to q/kdb+ servers
+- Execute q queries and commands
+- Persistent connection management
+
+## Requirements
+
+- Python 3.8+
+- qpython3 package
+- Access to a q/kdb+ server
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+Run the MCP server:
+
+```bash
+qmcp
+```
+
+### Environment Variables
+
+- `Q_DEFAULT_HOST` - Default connection info in format: `host`, `host:port`, or `host:port:user:passwd`
+
+### Connection Fallback Logic
+
+The `connect_to_q(host)` tool uses flexible fallback logic:
+
+1. **Full connection string** (has colons): Use directly, ignore `Q_DEFAULT_HOST`
+   - `connect_to_q("myhost:5001:user:pass")`
+2. **Port number only**: Combine with `Q_DEFAULT_HOST` or use `localhost`
+   - `connect_to_q(5001)` → Uses `Q_DEFAULT_HOST` settings with port 5001
+3. **No parameters**: Use `Q_DEFAULT_HOST` directly
+   - `connect_to_q()` → Uses `Q_DEFAULT_HOST` as-is
+4. **Hostname only**: Use as hostname with `Q_DEFAULT_HOST` port/auth or default port
+   - `connect_to_q("myhost")` → Combines with `Q_DEFAULT_HOST` settings
+
+### Tools
+
+1. `connect_to_q(host=None)` - Connect to q server with fallback logic
+2. `query_q(command)` - Execute q commands and return results
+
+### Known Limitations
+
+When using the MCP server, be aware of these limitations:
+
+- **Keyed tables**: Operations like `1!table` may fail during pandas conversion
+- **String vs Symbol distinction**: q strings and symbols may appear identical in output
+- **Type ambiguity**: Use q's `meta` and `type` commands to determine actual data types when precision matters
+- **Pandas conversion**: Some q-specific data structures may not convert properly to pandas DataFrames
+
+For type checking, use:
+```q
+meta table           / Check table column types and structure
+type variable        / Check variable type
+```

qmcp-0.1.0/README.md

@@ -0,0 +1,66 @@
+# qmcp Server
+
+A Model Context Protocol server for q/kdb+ integration.
+
+## Features
+
+- Connect to q/kdb+ servers
+- Execute q queries and commands
+- Persistent connection management
+
+## Requirements
+
+- Python 3.8+
+- qpython3 package
+- Access to a q/kdb+ server
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+Run the MCP server:
+
+```bash
+qmcp
+```
+
+### Environment Variables
+
+- `Q_DEFAULT_HOST` - Default connection info in format: `host`, `host:port`, or `host:port:user:passwd`
+
+### Connection Fallback Logic
+
+The `connect_to_q(host)` tool uses flexible fallback logic:
+
+1. **Full connection string** (has colons): Use directly, ignore `Q_DEFAULT_HOST`
+   - `connect_to_q("myhost:5001:user:pass")`
+2. **Port number only**: Combine with `Q_DEFAULT_HOST` or use `localhost`
+   - `connect_to_q(5001)` → Uses `Q_DEFAULT_HOST` settings with port 5001
+3. **No parameters**: Use `Q_DEFAULT_HOST` directly
+   - `connect_to_q()` → Uses `Q_DEFAULT_HOST` as-is
+4. **Hostname only**: Use as hostname with `Q_DEFAULT_HOST` port/auth or default port
+   - `connect_to_q("myhost")` → Combines with `Q_DEFAULT_HOST` settings
+
+### Tools
+
+1. `connect_to_q(host=None)` - Connect to q server with fallback logic
+2. `query_q(command)` - Execute q commands and return results
+
+### Known Limitations
+
+When using the MCP server, be aware of these limitations:
+
+- **Keyed tables**: Operations like `1!table` may fail during pandas conversion
+- **String vs Symbol distinction**: q strings and symbols may appear identical in output
+- **Type ambiguity**: Use q's `meta` and `type` commands to determine actual data types when precision matters
+- **Pandas conversion**: Some q-specific data structures may not convert properly to pandas DataFrames
+
+For type checking, use:
+```q
+meta table           / Check table column types and structure
+type variable        / Check variable type
+```

qmcp-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qmcp"
+version = "0.1.0"
+description = "MCP Server for q/kdb+ integration"
+authors = [{name = "Gabi Teodoru", email = "gabiteodoru@gmail.com"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "mcp",
+    "numpy>=1.8.0",
+    "pandas",
+    "more_itertools",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/gabiteodoru/qmcp"
+"Bug Tracker" = "https://github.com/gabiteodoru/qmcp/issues"
+"Source Code" = "https://github.com/gabiteodoru/qmcp"
+
+[project.scripts]
+qmcp = "qmcp.server:main"

qmcp-0.1.0/qmcp/__init__.py

@@ -0,0 +1,3 @@
+"""qmcp Server package"""
+
+__version__ = "0.1.0"

qmcp-0.1.0/qmcp/qlib.py

@@ -0,0 +1,143 @@
+"""
+Q/kdb+ connection utilities for qmcp
+Clean, minimal interface for connecting to and querying q servers
+"""
+
+from .qpython_compat import QConnection, MetaData
+import os
+import time
+import socket
+from .sugar import dmap, spl
+import pandas as pd
+import numpy as np
+
+
+def _get_hostname():
+    """Get current hostname"""
+    return socket.gethostname()
+
+
+class _QDecodeWrapper:
+    """Wrapper for QConnection that handles pandas DataFrame encoding/decoding"""
+    
+    def __init__(self, q):
+        self.q = q
+        
+    def __call__(self, *args, **kwargs):
+        # Handle DataFrame arguments
+        for arg in args:
+            if isinstance(arg, pd.DataFrame):
+                if not hasattr(arg, 'meta'):
+                    arg.meta = MetaData(qtype=98)
+                    
+                # Set date column metadata
+                for c in 'd, date'-spl:
+                    if (c in arg.columns and 
+                        isinstance(arg[c].dtype, np.dtype) and 
+                        arg[c].dtype != np.dtype(np.object_) and
+                        c not in arg.meta.__dict__):
+                        arg.meta[c] = 14
+                        
+                # Handle string columns
+                if 'strcols' in kwargs:
+                    for sc in kwargs['strcols']-spl:
+                        arg.meta[sc] = 0
+                        
+        # Execute query
+        r = self.q(*args, **kwargs)
+        
+        # Decode string/symbol columns in result
+        if type(r) == pd.DataFrame:
+            rd = r.meta.as_dict()
+            for col in rd:
+                if rd[col] in (0, 11):  # string or symbol columns
+                    r[col] = r[col].map(dmap(lambda x: x.decode('utf-8'), r[col].drop_duplicates()))
+                    
+        return r
+
+
+def connect_to_q(host=None):
+    """
+    Connect to q server with flexible fallback logic for MCP
+    
+    Args:
+        host: None, port number, 'host:port', or full connection string
+        
+    Fallback logic:
+    1. If host has colons, use directly (ignores Q_DEFAULT_HOST)
+    2. If no envvar and no parameter, fail
+    3. If port provided, combine with Q_DEFAULT_HOST or localhost
+    4. Use Q_DEFAULT_HOST if available
+    
+    Returns:
+        _QDecodeWrapper instance
+    """
+    # 4) If host has colons, use it directly (ignore Q_DEFAULT_HOST)
+    if host and ':' in str(host):
+        return _qConnect(str(host), True)
+    
+    # Get Q_DEFAULT_HOST environment variable
+    default_host = os.environ.get('Q_DEFAULT_HOST')
+    
+    # 2) Fail if no envvar and no parameter
+    if not default_host and not host:
+        raise ValueError("No connection info: set Q_DEFAULT_HOST or provide host parameter")
+    
+    # 3) If host is just a port number, combine with default host info
+    if host and str(host).isdigit():
+        port = str(host)
+        if default_host:
+            # Extract host[:user:passwd] from Q_DEFAULT_HOST, replace port
+            parts = default_host.split(':')
+            if len(parts) >= 2:
+                # Replace port in Q_DEFAULT_HOST
+                parts[1] = port
+                return _qConnect(':'.join(parts), True)
+            else:
+                # Q_DEFAULT_HOST is just hostname
+                return _qConnect(f"{default_host}:{port}", True)
+        else:
+            # No Q_DEFAULT_HOST, use localhost
+            return _qConnect(f"localhost:{port}", True)
+    
+    # 1) Use Q_DEFAULT_HOST (host, host:port, or host:port:user:passwd)
+    if default_host:
+        return _qConnect(default_host, True)
+    
+    # Should never reach here due to check above
+    raise ValueError("Invalid connection parameters")
+
+
+def _qConnect(qCredentials, pandas):
+    """
+    Connect to q server with retry logic
+    
+    Args:
+        qCredentials: 'host:port' or 'host:port:user:passwd'
+        pandas: return pandas-enabled connection
+        
+    Returns:
+        QConnection or _QDecodeWrapper
+    """
+    qCreds = tuple(qCredentials.split(':'))
+    host, port, user, passwd = qCreds if len(qCreds) == 4 else (qCreds + (None, None))
+    port = int(port)
+    
+    if host == _get_hostname():
+        host = 'localhost'
+        
+    # Retry connection for up to 5 seconds
+    t = time.time()    
+    while time.time() - t < 5:
+        try:
+            q = QConnection(host, port, user, passwd, pandas=pandas)
+            q.open()
+            return _QDecodeWrapper(q) if pandas else q
+        except Exception as e:
+            print(f"Connection attempt failed: {e}")
+            time.sleep(0.1)
+            
+    # Final attempt without retry
+    q = QConnection(host, port, user, passwd, pandas=pandas)
+    q.open()
+    return _QDecodeWrapper(q) if pandas else q

qmcp-0.1.0/qmcp/qpython/__init__.py

@@ -0,0 +1,69 @@
+#
+#  Copyright (c) 2011-2014 Exxeleron GmbH
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+
+__all__ = ['qconnection', 'qtype', 'qtemporal', 'qcollection']
+
+
+__version__ = '2.0.0'
+
+
+
+try:
+    from qpython.fastutils import uncompress
+except:
+    __is_cython_enabled__ = False
+else:
+    __is_cython_enabled__ = True
+
+
+class MetaData(object):
+    '''Utility class for enriching data structures with meta data, e.g. qtype hint.'''
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+    def __repr__(self):
+        if not self.__dict__.items():
+            return 'metadata()'
+
+        s = ['metadata(']
+        for k, v in self.__dict__.items():
+            s.append('%s=%s' % (k, repr(v)))
+            s.append(', ')
+        s[-1] = ')'
+        return ''.join(s)
+
+    def __getattr__(self, attr):
+        return None
+
+    def __getitem__(self, key):
+        return self.__dict__.get(key, None)
+
+    def __setitem__(self, key, value):
+        self.__dict__[key] = value
+
+    def as_dict(self):
+        return self.__dict__.copy()
+
+    def union_dict(self, **kw):
+        return dict(list(self.as_dict().items()) + list(kw.items()))
+
+
+
+CONVERSION_OPTIONS = MetaData(raw = False,
+                              numpy_temporals = False,
+                              pandas = False,
+                              single_char_strings = False
+                             )

qmcp-0.1.0/qmcp/qpython/_pandas.py

@@ -0,0 +1,221 @@
+#
+#  Copyright (c) 2011-2014 Exxeleron GmbH
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+#
+
+import pandas
+import struct
+import sys
+if sys.version > '3':
+    basestring = (str, bytes)
+
+from collections import OrderedDict
+
+from qpython import MetaData
+from qpython.qreader import QReader, QReaderException
+from qpython.qcollection import QDictionary, qlist
+from qpython.qwriter import QWriter, QWriterException
+from qpython.qtype import *
+
+
+
+class PandasQReader(QReader):
+
+    _reader_map = dict.copy(QReader._reader_map)
+    parse = Mapper(_reader_map)
+
+    @parse(QDICTIONARY)
+    def _read_dictionary(self, qtype = QDICTIONARY):
+        if self._options.pandas:
+            keys = self._read_object()
+            values = self._read_object()
+
+            if isinstance(keys, pandas.DataFrame):
+                if not isinstance(values, pandas.DataFrame):
+                    raise QReaderException('Keyed table creation: values are expected to be of type pandas.DataFrame. Actual: %s' % type(values))
+
+                indices = keys.columns
+                table = keys
+                table.meta = keys.meta
+                table.meta.qtype = QKEYED_TABLE
+
+                for column in values.columns:
+                    table[column] = values[column]
+                    table.meta[column] = values.meta[column]
+
+                table.set_index([column for column in indices], inplace = True)
+
+                return table
+            else:
+                keys = keys if not isinstance(keys, pandas.Series) else keys.values
+                values = values if not isinstance(values, pandas.Series) else values.values
+                return QDictionary(keys, values)
+        else:
+            return QReader._read_dictionary(self, qtype = qtype)
+
+
+    @parse(QTABLE)
+    def _read_table(self, qtype = QTABLE):
+        if self._options.pandas:
+            self._buffer.skip()  # ignore attributes
+            self._buffer.skip()  # ignore dict type stamp
+
+            columns = self._read_object()
+            self._buffer.skip() # ignore generic list type indicator
+            data = QReader._read_general_list(self, qtype)
+
+            odict = OrderedDict()
+            meta = MetaData(qtype = QTABLE)
+            for i in range(len(columns)):
+                column_name = columns[i] if isinstance(columns[i], str) else columns[i].decode("utf-8")
+                if isinstance(data[i], str):
+                    # convert character list (represented as string) to numpy representation
+                    meta[column_name] = QSTRING
+                    odict[column_name] = pandas.Series(list(data[i]), dtype = numpy.str).replace(b' ', numpy.nan)
+                elif isinstance(data[i], bytes):
+                    # convert character list (represented as string) to numpy representation
+                    meta[column_name] = QSTRING
+                    odict[column_name] = pandas.Series(list(data[i].decode()), dtype = str).replace(b' ', numpy.nan)
+                elif isinstance(data[i], (list, tuple)):
+                    meta[column_name] = QGENERAL_LIST
+                    tarray = numpy.ndarray(shape = len(data[i]), dtype = numpy.dtype('O'))
+                    for j in range(len(data[i])):
+                        tarray[j] = data[i][j]
+                    odict[column_name] = tarray
+                else:
+                    meta[column_name] = data[i].meta.qtype
+                    odict[column_name] = data[i]
+
+            df = pandas.DataFrame(odict)
+            df._metadata = ["meta"]
+            df.meta = meta
+            return df
+        else:
+            return QReader._read_table(self, qtype = qtype)
+
+
+    def _read_list(self, qtype):
+        if self._options.pandas:
+            self._options.numpy_temporals = True
+
+        qlist = QReader._read_list(self, qtype = qtype)
+
+        if self._options.pandas:
+            if -abs(qtype) not in [QBOOL, QMONTH, QDATE, QDATETIME, QMINUTE, QSECOND, QTIME, QTIMESTAMP, QTIMESPAN, QSYMBOL]:
+                null = QNULLMAP[-abs(qtype)][1]
+                ps = pandas.Series(data = qlist).replace(null, numpy.nan)
+            else:
+                ps = pandas.Series(data = qlist)
+
+            ps.meta = MetaData(qtype = qtype)
+            return ps
+        else:
+            return qlist
+
+
+    @parse(QGENERAL_LIST)
+    def _read_general_list(self, qtype = QGENERAL_LIST):
+        qlist = QReader._read_general_list(self, qtype)
+        if self._options.pandas:
+            return [numpy.nan if isinstance(element, basestring) and element == b' ' else element for element in qlist]
+        else:
+            return qlist
+
+
+
+class PandasQWriter(QWriter):
+
+    _writer_map = dict.copy(QWriter._writer_map)
+    serialize = Mapper(_writer_map)
+
+
+    @serialize(pandas.Series)
+    def _write_pandas_series(self, data, qtype = None):
+        if qtype is not None:
+            qtype = -abs(qtype)
+
+        if qtype is None and hasattr(data, 'meta'):
+            qtype = -abs(data.meta.qtype)
+
+        if data.dtype == '|S1':
+            qtype = QCHAR
+
+        if qtype is None:
+            qtype = Q_TYPE.get(data.dtype.type, None)
+
+        if qtype is None and data.dtype.type in (numpy.datetime64, numpy.timedelta64):
+            qtype = TEMPORAL_PY_TYPE.get(str(data.dtype), None)
+
+        if qtype is None:
+            # determinate type based on first element of the numpy array
+            qtype = Q_TYPE.get(type(data.iloc[0]), QGENERAL_LIST)
+
+            if qtype == QSTRING:
+                # assume we have a generic list of strings -> force representation as symbol list
+                qtype = QSYMBOL
+
+        if qtype is None:
+            raise QWriterException('Unable to serialize pandas series %s' % data)
+
+        if qtype == QGENERAL_LIST:
+            self._write_generic_list(data.values)
+        elif qtype == QCHAR:
+            self._write_string(data.replace(numpy.nan, ' ').values.astype(numpy.bytes_).tobytes())
+        elif data.dtype.type not in (numpy.datetime64, numpy.timedelta64):
+            data = data.fillna(QNULLMAP[-abs(qtype)][1])
+            data = data.values
+
+            if PY_TYPE[qtype] != data.dtype:
+                data = data.astype(PY_TYPE[qtype])
+
+            self._write_list(data, qtype = qtype)
+        else:
+            data = data.values
+            data = data.astype(TEMPORAL_Q_TYPE[qtype])
+            self._write_list(data, qtype = qtype)
+
+
+    @serialize(pandas.DataFrame)
+    def _write_pandas_data_frame(self, data, qtype = None):
+        data_columns = data.columns.values
+
+        if hasattr(data, 'meta') and data.meta.qtype == QKEYED_TABLE:
+            # data frame represents keyed table
+            self._buffer.write(struct.pack('=b', QDICTIONARY))
+            self._buffer.write(struct.pack('=bxb', QTABLE, QDICTIONARY))
+            index_columns = data.index.names
+            self._write(qlist(numpy.array(index_columns), qtype = QSYMBOL_LIST))
+            data.reset_index(inplace = True)
+            self._buffer.write(struct.pack('=bxi', QGENERAL_LIST, len(index_columns)))
+            for column in index_columns:
+                self._write_pandas_series(data[column], qtype = data.meta[column] if hasattr(data, 'meta') else None)
+
+            data.set_index(index_columns, inplace = True)
+
+        self._buffer.write(struct.pack('=bxb', QTABLE, QDICTIONARY))
+        self._write(qlist(numpy.array(data_columns), qtype = QSYMBOL_LIST))
+        self._buffer.write(struct.pack('=bxi', QGENERAL_LIST, len(data_columns)))
+        for column in data_columns:
+            self._write_pandas_series(data[column], qtype = data.meta[column] if hasattr(data, 'meta') else None)
+
+
+    @serialize(tuple, list)
+    def _write_generic_list(self, data):
+        if self._options.pandas:
+            self._buffer.write(struct.pack('=bxi', QGENERAL_LIST, len(data)))
+            for element in data:
+                # assume nan represents a string null
+                self._write(' ' if type(element) in [float, numpy.float32, numpy.float64] and numpy.isnan(element) else element)
+        else:
+            QWriter._write_generic_list(self, data)