Add TypeScript conversion plan for Noko MCP Server

 rel #1

- Created a comprehensive plan for converting the Noko MCP Server from Python to TypeScript.
- Outlined project setup, including TypeScript configuration, directory structure, and environment variable management.
- Defined tasks for implementing core server functionality, tools module, API integration, authentication, testing framework, and documentation.
- Included notes on best practices for TypeScript development and project distribution.

Author: sirkitree

.env.example

@@ -1,2 +1,2 @@
-# Noko API token
-NOKO_TOKEN=your_noko_api_token_here 
+# Noko API token from https://nokotime.com/api/
+NOKO_API_TOKEN=your_token_here 

.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "root": true,
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off"
+  }
+} 

.gitignore

@@ -8,3 +8,21 @@ wheels/
 
 # Virtual environments
 .venv
+
+# Node.js dependencies
+node_modules/
+
+# TypeScript build output
+dist/
+*.tsbuildinfo
+
+# Environment variables
+.env
+
+# IDE files
+.vscode/
+.idea/
+
+# Logs
+*.log
+npm-debug.log*

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2
+} 

.python-version

@@ -1,190 +1,71 @@
-# MCP Noko Server
+# Noko MCP Server
 
-A Model Context Protocol (MCP) server for integrating Noko time tracking with Claude Desktop.
+A Model Context Protocol (MCP) server for interacting with the [Noko](https://nokotime.com/) time tracking API.
 
 ## Features
 
-- Full Noko API v2 integration
-- Secure authentication handling
-- Time entry management
-- Project and user listing
-- Error handling and validation
-- Async/await support
+This MCP server allows Claude and other AI assistants to:
+
+- List time entries with filtering options
+- Create new time entries
+- List projects
+- List users
 
 ## Installation
 
-1. Ensure you have Python 3.9+ installed
-2. Clone this repository:
 ```bash
+# Clone the repository
 git clone https://github.com/yourusername/mcp-nokotime.git
 cd mcp-nokotime
-```
-
-3. Install `uv` if you haven't already:
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
 
-4. Create and activate a virtual environment:
-```bash
-uv venv
-source .venv/bin/activate  # On Unix/macOS
-# or
-.venv\Scripts\activate  # On Windows
-```
+# Install dependencies
+npm install
 
-5. Install the package in development mode:
-```bash
-uv pip install -e .
+# Build the project
+npm run build
 ```
 
-6. Test the server:
-```bash
-python -m nokotime.server
-```
-
-### Claude Desktop Setup
-
-1. Open Claude Desktop settings at:
-   - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-2. Add or update the Noko server configuration:
-```json
-{
-  "mcpServers": {
-    "noko": {
-      "command": "/Users/sirkitree/repos/mcp-nokotime/.venv/bin/python3",
-      "args": [
-        "-m",
-        "nokotime.server"
-      ],
-      "env": {
-        "NOKO_API_TOKEN": "your_existing_token",
-        "PYTHONPATH": "/Users/sirkitree/repos/mcp-nokotime"
-      }
-    }
-  }
-}
-```
-
-**Important Notes:**
-- The `command` should point to Python in your virtual environment (shown above is an example path)
-- Keep your existing `NOKO_API_TOKEN` value; don't replace it with the example value shown above
-- Make sure you've completed all installation steps before starting Claude Desktop
-- Restart Claude Desktop after making configuration changes
-- If you get connection errors, check Claude Desktop logs at `~/Library/Logs/Claude/mcp*.log`
-
-## Available Tools
+## Configuration
 
-### 1. List Time Entries
-Lists time entries with optional filters.
-
-**Example:**
-```json
-{
-  "from": "2023-12-01",
-  "to": "2023-12-31",
-  "user_ids": [123],
-  "project_ids": [456]
-}
-```
+Create a `.env` file in the root directory with the following content:
 
-### 2. Create Time Entry
-Creates a new time entry.
-
-**Example:**
-```json
-{
-  "date": "2023-12-14",
-  "minutes": 60,
-  "description": "Working on project documentation",
-  "project_id": 123
-}
 ```
-
-### 3. List Projects
-Lists all available projects.
-
-**Example:**
-```json
-{
-  "state": "active"  // Options: "active", "archived", "all"
-}
+NOKO_API_TOKEN=your_noko_api_token
 ```
 
-### 4. List Users
-Lists all users.
-
-**Example:**
-```json
-{
-  "state": "active"  // Options: "active", "suspended", "all"
-}
-```
+You can obtain your Noko API token from your Noko account settings.
 
-## Development
+## Usage
 
-### Running Tests
+### Running the Server
 
-Run the test suite with:
 ```bash
-pytest
+npm start
 ```
 
-For test coverage report:
+### Development
+
 ```bash
-pytest --cov=nokotime
+npm run dev
 ```
 
-### Project Structure
-
-- `src/nokotime/server.py`: Main server implementation
-- `src/nokotime/tools.py`: Tool definitions and schemas
-- `tests/`: Test suite
-  - `conftest.py`: Test fixtures and configuration
-  - `test_server.py`: Server tests
-  - `test_tools.py`: Tool schema tests
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Authentication Errors**
-   - Ensure your Noko API token is valid
-   - Check that the token is correctly set in Claude Desktop configuration
-   - Verify the `X-NokoToken` header is being sent with requests
-
-2. **Connection Issues**
-   - Check your internet connection
-   - Verify the Noko API is accessible
-   - Check for any firewall restrictions
-
-3. **Tool Errors**
-   - Ensure request parameters match the tool schemas
-   - Check date formats are YYYY-MM-DD
-   - Verify project and user IDs exist in your Noko account
+## Available Tools
 
-4. **Virtual Environment Issues**
-   - Make sure the virtual environment is activated when installing packages
-   - Verify the path to Python in the Claude Desktop configuration matches your virtual environment
-   - On Windows, use backslashes in paths: `.venv\Scripts\python`
+The server provides the following tools to AI assistants:
 
-### Debug Mode
+1. `noko_list_entries` - List time entries with optional filters
+   - Parameters: `user_ids[]`, `project_ids[]`, `from`, `to`, `invoiced`, `updated_from`, `updated_to`, `per_page`, `page`
 
-To enable debug logging, set the environment variable:
-```bash
-export MCP_DEBUG=1
-```
+2. `noko_create_entry` - Create a new time entry
+   - Required parameters: `date`, `minutes`, `description`
+   - Optional parameters: `project_id`, `user_id`, `billable`, `tags`, `invoice_id`
 
-## Contributing
+3. `noko_list_projects` - List all available projects
+   - Parameters: `name`, `state`, `billing_increment`, `enabled_for_tracking`, `per_page`, `page`
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests for new functionality
-5. Submit a pull request
+4. `noko_list_users` - List all users
+   - Parameters: `name`, `email`, `state`, `role`, `per_page`, `page`
 
 ## License
 
-MIT License - see LICENSE file for details
+MIT

README.md

@@ -0,0 +1,13 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest',
+  },
+  testRegex: '(/tests/.*\\.(test|spec))\\.(ts|tsx)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  collectCoverage: true,
+  coverageReporters: ['text', 'lcov'],
+  coverageDirectory: 'coverage',
+};