@timofi/context-server 1.0.0

package/README.md

@@ -0,0 +1,572 @@
+# Timofi Context Server
+
+<img alt="gitleaks badge" src="https://img.shields.io/badge/protected%20by-gitleaks-blue">
+
+A secure, scalable repository-aware memory and code intelligence platform for AI assistants. The system consists of two main components: a **Timofi API Server** for centralized processing and secure token storage, and a lightweight **MCP Client** for local AI assistant integration.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  %% -------- CLIENT LAYER --------
+  subgraph CLIENTS["🖥️ Client Applications"]
+    CC[Claude Code]
+    CHAT[ChatGPT]
+    IDE[IDEs & Editors]
+    CLI[CLI Tools]
+  end
+
+  %% -------- MCP CLIENT (LOCAL) --------
+  subgraph MCP_CLIENT["📡 MCP Client (Local)"]
+    MCP_SERVER[MCP Protocol Handler]
+    API_CLIENT[Timofi API Client]
+    CONFIG[Config Manager]
+  end
+
+  %% -------- TIMOFI API SERVER (CENTRALIZED) --------
+  subgraph API_SERVER["🏗️ Timofi API Server (Centralized)"]
+    AUTH_API[Authentication Service]
+    TOKEN_VAULT[GitHub Token Vault]
+    MEMORY_API[Memory Service API]
+    CODE_API[Code Intelligence API]
+    REPO_API[Repository Service API]
+    WORKER[Background Workers]
+  end
+
+  %% -------- DATA LAYER --------
+  subgraph DATA_LAYER["💾 Data Storage (Server-Side)"]
+    POSTGRES[(PostgreSQL)]
+    QDRANT[(Vector Database)]
+    NEO4J[(Graph Database)]
+    REDIS[(Cache Layer)]
+  end
+
+  %% -------- EXTERNAL SERVICES --------
+  subgraph EXTERNAL["🌐 External Services"]
+    GITHUB[GitHub API]
+    EMBEDDING[Embedding Services]
+  end
+
+  %% Connections
+  CLIENTS --> MCP_CLIENT
+  MCP_CLIENT --> API_SERVER
+  API_SERVER --> DATA_LAYER
+  API_SERVER --> EXTERNAL
+
+  %% Details
+  MCP_SERVER -.->|"Single API Key"| API_CLIENT
+  AUTH_API -.->|"Secure Storage"| TOKEN_VAULT
+  TOKEN_VAULT -.->|"On Behalf Of Users"| GITHUB
+```
+
+## Features
+
+### 🔒 Secure Architecture
+
+- **Centralized Token Management**: GitHub tokens stored securely on the API server
+- **Single API Key**: Users only need one Timofi API key locally
+- **Zero Local Secrets**: No sensitive credentials stored on user devices
+- **Enterprise Security**: End-to-end encryption, audit logs, and access controls
+
+### 🧠 Repository-Scoped Memory
+
+- **Intelligent Memory**: Context-aware memory storage and retrieval per repository
+- **Vector Embeddings**: Semantic search across conversational history and insights
+- **Multi-Repository Support**: Seamless handling of organization-wide repositories
+- **Privacy by Design**: Repository-scoped data isolation with secure access controls
+
+### 🔍 Advanced Code Intelligence
+
+- **Real-time Code Analysis**: Live symbol extraction and relationship mapping
+- **Semantic Code Search**: Natural language queries for code discovery
+- **Background Indexing**: Automated repository processing with progress tracking
+- **Cross-Reference Analysis**: Find related functions, tests, and documentation
+
+### 🔗 Universal Integration
+
+- **MCP Protocol**: Compatible with Claude Code, ChatGPT, and major IDEs
+- **API First**: RESTful API for custom integrations and advanced use cases
+- **Lightweight Client**: Minimal local footprint with powerful remote capabilities
+- **Developer Friendly**: Simple setup with comprehensive documentation
+
+## Installation
+
+### Quick Start (Recommended)
+
+1. **Install MCP Client**
+   ```bash
+   npm install -g @goldcode-io/timofi-context-server
+   ```
+
+2. **Get Your API Key**
+   - Visit [Timofi Console](https://console.timofi.goldcode.io)
+   - Sign up with GitHub OAuth
+   - Generate your Timofi API key
+   - Authorize GitHub repositories you want to access
+
+3. **Configure Claude Desktop**
+   ```json
+   {
+     "mcpServers": {
+       "timofi": {
+         "command": "timofi-context-server",
+         "env": {
+           "TIMOFI_API_KEY": "your-api-key-here"
+         }
+       }
+     }
+   }
+   ```
+
+That's it! No local secrets, no complex setup, no Docker containers to manage.
+
+### Self-Hosted Installation (Advanced)
+
+For organizations requiring complete control over data and infrastructure:
+
+#### Prerequisites
+- Node.js 18+
+- Docker and Docker Compose
+- PostgreSQL, Qdrant, Neo4j, Redis access
+
+#### API Server Setup
+
+1. **Clone and Install API Server**
+   ```bash
+   git clone https://github.com/goldcode-io/timofi-api-server.git
+   cd timofi-api-server
+   npm install
+   ```
+
+2. **Configure Environment**
+   ```bash
+   cp .env.example .env
+   # Configure database connections, encryption keys, etc.
+   ```
+
+3. **Start Infrastructure**
+   ```bash
+   docker-compose up -d  # PostgreSQL, Qdrant, Neo4j, Redis
+   npm run migrate      # Run database migrations
+   npm start           # Start API server
+   ```
+
+#### MCP Client Setup
+
+1. **Install Local MCP Client**
+   ```bash
+   npm install -g @goldcode-io/timofi-context-server
+   ```
+
+2. **Configure for Self-Hosted**
+   ```json
+   {
+     "mcpServers": {
+       "timofi": {
+         "command": "timofi-context-server",
+         "env": {
+           "TIMOFI_API_URL": "http://localhost:3000",
+           "TIMOFI_API_KEY": "your-self-hosted-key"
+         }
+       }
+     }
+   }
+   ```
+
+## Configuration
+
+### MCP Client Configuration
+
+The MCP client requires minimal configuration:
+
+```json
+{
+  "mcpServers": {
+    "timofi": {
+      "command": "timofi-context-server",
+      "env": {
+        "TIMOFI_API_KEY": "your-api-key-here",
+        "TIMOFI_API_URL": "https://api.timofi.goldcode.io"  // Optional: defaults to hosted service
+      }
+    }
+  }
+}
+```
+
+### API Server Configuration (Self-Hosted Only)
+
+```bash
+# Database Configuration
+DATABASE_URL=postgresql://user:pass@localhost:5432/timofi
+QDRANT_URL=http://localhost:6333
+NEO4J_URL=bolt://localhost:7687
+REDIS_URL=redis://localhost:6379
+
+# Security Configuration
+ENCRYPTION_KEY=your-32-byte-encryption-key
+JWT_SECRET=your-jwt-secret
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+
+# External Services
+OPENAI_API_KEY=your-openai-key  # For embeddings
+GITHUB_APP_ID=your-github-app-id
+GITHUB_APP_PRIVATE_KEY=your-github-app-private-key
+
+# Server Configuration
+PORT=3000
+LOG_LEVEL=info
+NODE_ENV=production
+
+# Webhooks: public URL of this API (required for auto-created GitHub webhooks)
+# GitHub will send push events here; use your real API host (e.g. https://api.yourdomain.com)
+API_BASE_URL=https://your-api-host.com
+```
+
+### Repository Access Setup
+
+1. **Via Web Console (Recommended)**
+   - Visit [Timofi Console](https://console.timofi.goldcode.io)
+   - Connect your GitHub account
+   - Select repositories to authorize
+   - Generate scoped access tokens
+
+2. **Via API (Advanced)**
+   ```bash
+   curl -X POST https://api.timofi.goldcode.io/v1/auth/github/connect \
+     -H "Authorization: Bearer YOUR_TIMOFI_API_KEY" \
+     -H "Content-Type: application/json" \
+     -d '{"github_token": "ghp_your_github_token"}'
+   ```
+
+### Webhooks (push → re-index)
+
+When a webhook is active for a repository, **pushes to the default branch** create a pending indexing task; the worker picks it up within ~30 seconds and runs a new index.
+
+**1. Auto-creation on connect**  
+When you connect a repository (Dashboard or `POST /api/v1/repositories/connect`), the server tries to create a GitHub webhook. For that to work:
+
+- Set **`API_BASE_URL`** (or `NEXT_PUBLIC_API_URL`) to the **public URL of your API server** (e.g. `https://api.yourdomain.com`). GitHub must be able to reach this URL; do not use `localhost` in production.
+- The user connecting the repo must have a GitHub token stored (Dashboard → Settings → GitHub tokens).
+
+**2. Create webhook manually** (if auto-creation failed or the repo was connected earlier without it)
+
+- **Dashboard:** Repositories → select the repo → **Manage webhook** (webhook icon) → **Create Webhook**. The default URL is the current page origin + `/api/v1/webhooks/github`. If your API runs on a different host than the dashboard, enter the full API URL (e.g. `https://api.yourdomain.com/api/v1/webhooks/github`).
+- **API:**  
+  `POST /api/v1/repositories/:id/webhooks`  
+  Body: `{ "webhookUrl": "https://your-api-host/api/v1/webhooks/github", "events": ["push", "repository", "delete"], "active": true }`  
+  Requires authentication and a GitHub token for a user with access to the repo.
+
+**3. Check**  
+- In GitHub: repo → Settings → Webhooks. You should see a webhook pointing to your API URL; “Recent Deliveries” shows push events.  
+- Only pushes to the **default branch** (e.g. `main`) trigger indexing.
+
+**4. 401 Invalid signature**  
+- The webhook **secret** is not visible anywhere (stored in the app DB and in GitHub). If you get 401, the secret may not match (e.g. webhook was edited in GitHub with a new secret).  
+- **Fix:** Dashboard → Repositories → select repo → Manage webhook → **Regenerate secret** (updates both GitHub and the app).  
+- Or via API: `POST /api/v1/repositories/:id/webhooks/regenerate` with body `{ "webhookUrl": "https://your-api-host/api/v1/webhooks/github" }` (requires auth and a GitHub token).
+
+## Usage
+
+### Command Line Interface
+
+```bash
+# Start MCP server for a specific repository
+timofi-context --repository owner/repo-name
+
+# Start with custom configuration
+timofi-context --repository owner/repo-name --config /path/to/config.json
+
+# Index a repository
+timofi-context index --repository owner/repo-name
+
+# Query memories
+timofi-context query --repository owner/repo-name --query "authentication logic"
+
+# List supported repositories
+timofi-context list-repos
+```
+
+### MCP Tools
+
+The server provides the following MCP tools:
+
+#### Memory Management
+
+- `store_memory`: Store conversation context or code insights
+- `retrieve_memories`: Get relevant memories for current context
+- `search_memories`: Semantic search across stored memories
+
+#### Code Retrieval
+
+- `search_code`: Find relevant code snippets and symbols
+- `get_file_context`: Retrieve file content with related symbols
+- `find_tests`: Locate tests related to specific code
+- `get_dependencies`: Analyze code dependencies and relationships
+
+#### Repository Management
+
+- `index_repository`: Index a repository for search and memory
+- `check_access`: Verify user access to repository
+- `get_repo_info`: Retrieve repository metadata and structure
+
+## Self-Hosted Services
+
+### Docker Compose Services
+
+The included `docker-compose.yml` provides:
+
+- **Mem0**: Memory management service
+- **Sourcegraph**: Code intelligence and search
+- **Qdrant**: Vector database for embeddings
+- **Redis**: Caching layer for improved performance
+
+### Service Configuration
+
+#### Mem0 Configuration
+
+```yaml
+mem0:
+  image: mem0ai/mem0:latest
+  ports:
+    - '8000:8000'
+  environment:
+    - VECTOR_STORE_URL=http://qdrant:6333
+  volumes:
+    - mem0_data:/app/data
+```
+
+#### Sourcegraph Configuration
+
+```yaml
+sourcegraph:
+  image: sourcegraph/server:latest
+  ports:
+    - '3080:7080'
+  environment:
+    - SRC_LOG_LEVEL=warn
+  volumes:
+    - sourcegraph_data:/var/opt/sourcegraph
+```
+
+## API Reference
+
+### Authentication
+
+All requests require a valid GitHub token that provides access to the target repository:
+
+```bash
+curl -H "Authorization: Bearer ghp_your_token" \
+     -H "X-Repository: owner/repo-name" \
+     http://localhost:3000/api/memories
+```
+
+### Memory Endpoints
+
+#### Store Memory
+
+```bash
+POST /api/memories
+{
+  "content": "User discussed authentication implementation",
+  "context": {
+    "file": "src/auth.js",
+    "function": "validateToken",
+    "conversation_id": "conv_123"
+  },
+  "repository": "owner/repo-name"
+}
+```
+
+#### Retrieve Memories
+
+```bash
+GET /api/memories?query=authentication&repository=owner/repo-name&limit=10
+```
+
+### Code Search Endpoints
+
+#### Search Code
+
+```bash
+GET /api/code/search?q=authentication&repository=owner/repo-name&type=function
+```
+
+#### Get File Context
+
+```bash
+GET /api/code/context?file=src/auth.js&repository=owner/repo-name
+```
+
+## Development
+
+### Project Structure
+
+```
+timofi-context-server/
+├── src/
+│   ├── server.ts           # MCP server implementation
+│   ├── memory/             # Memory management
+│   │   ├── mem0.ts
+│   │   └── zep.ts
+│   ├── code/               # Code retrieval
+│   │   ├── sourcegraph.ts
+│   │   └── llamaindex.ts
+│   ├── auth/               # GitHub authentication
+│   └── utils/              # Utilities
+├── docker-compose.yml      # Self-hosted services
+├── package.json
+└── README.md
+```
+
+### Scripts
+
+```bash
+# Development
+npm run dev          # Start with hot reload
+npm run build        # Build for production
+npm run test         # Run tests
+npm run lint         # Lint code
+
+# Docker
+npm run docker:up    # Start all services
+npm run docker:down  # Stop all services
+npm run docker:logs  # View service logs
+
+# Utilities
+npm run index-repo   # Index a repository
+npm run clean-cache  # Clear all caches
+```
+
+### Testing
+
+```bash
+# Unit tests
+npm test
+
+# Integration tests with services
+npm run test:integration
+
+# Test specific repository
+npm run test -- --repository owner/repo-name
+```
+
+## Security
+
+### Access Control
+
+- Repository access verified via GitHub API before each request
+- GitHub tokens validated and scoped appropriately
+- Memory and code data isolated by repository
+
+### Data Privacy
+
+- All data stored in self-hosted services
+- No data sent to external services without explicit configuration
+- Configurable data retention policies
+
+### Best Practices
+
+- Use fine-grained GitHub tokens with minimal required permissions
+- Regularly rotate API keys and tokens
+- Monitor access logs for suspicious activity
+- Keep self-hosted services updated
+
+## Troubleshooting
+
+### Common Issues
+
+#### Service Connection Errors
+
+```bash
+# Check service status
+docker-compose ps
+
+# View service logs
+docker-compose logs mem0
+docker-compose logs sourcegraph
+```
+
+#### GitHub Authentication
+
+```bash
+# Test token validity
+curl -H "Authorization: Bearer ghp_your_token" \
+     https://api.github.com/user
+
+# Check repository access
+curl -H "Authorization: Bearer ghp_your_token" \
+     https://api.github.com/repos/owner/repo-name
+```
+
+#### MCP Connection Issues
+
+```bash
+# Test MCP server
+timofi-context --test-connection
+
+# Debug mode
+timofi-context --repository owner/repo-name --debug
+```
+
+### Logs
+
+Service logs are available at:
+
+- MCP Server: `~/.timofi-context/logs/server.log`
+- Memory Service: `docker-compose logs mem0`
+- Code Service: `docker-compose logs sourcegraph`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit changes: `git commit -m 'Add amazing feature'`
+4. Push to branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📧 Email: support@goldcode.io
+- 🐛 Issues: [GitHub Issues](https://github.com/goldcode-io/timofi-context-server/issues)
+- 📖 Documentation: [Wiki](https://github.com/goldcode-io/timofi-context-server/wiki)
+
+## Secret Scanning with Gitleaks
+
+This repository uses Gitleaks to detect hardcoded secrets and prevent sensitive data from being committed.    
+To guarantee consistent behavior between local development and CI, all scans are performed as filesystem scans (not Git history scans).
+
+There are two scanning modes, depending on when and how they are executed.
+
+### 1. Github Actions Scans (Pull Requests and Manual)
+
+Gitleaks is executed on:
+- Every Pull Request
+- Manually: via GitHub Actions → Run workflow
+
+**What is scanned automatically ?**
+- On PRs: The diff between the current state of the repository filesystem compared to your changes
+- Manually: All filesystem on (trunk/master/main/default)
+- Git history and other branches are not scanned
+
+This is the primary protection mechanism for day-to-day development.
+
+### 2. Running a full scan locally
+
+Developers can run a full scan locally at any time:
+```shell
+$ make gitleaks
+```
+This executes a full filesystem scan using the project’s `.gitleaks.local.toml` configuration.  
+Make sure you have Gitleaks installed locally ([GitLeaks Repository](https://github.com/gitleaks/gitleaks?tab=readme-ov-file#installing)).
+
+### About .gitleaks.toml file
+The `.gitleaks.local.toml` and `.gitleaks.ci.toml` files defines allowlists and rules to reduce noise, such as:
+- test files and fixtures
+- examples and documentation
+- .env files and templates
+
+This keeps results actionable and avoids reporting known non-issues.

package/dist/index.js

@@ -0,0 +1 @@
+import{Server as T}from"@modelcontextprotocol/sdk/server/index.js";import{StdioServerTransport as b}from"@modelcontextprotocol/sdk/server/stdio.js";import{InitializeRequestSchema as P,ListToolsRequestSchema as I,ListResourcesRequestSchema as E,PingRequestSchema as O,CallToolRequestSchema as k}from"@modelcontextprotocol/sdk/types.js";import{EventEmitter as L}from"events";import{randomUUID as M}from"crypto";import{createLogger as C,format as a,transports as y}from"winston";var c=class u{logger;requestContext;constructor(e="info",t="development"){let r=t==="development";this.logger=C({level:e,format:a.combine(a.timestamp(),a.errors({stack:!0}),a.json(),r?a.prettyPrint():a.uncolorize()),defaultMeta:{service:"timofi-context-server",version:process.env.npm_package_version||"1.0.0"},transports:[new y.Console({stderrLevels:["error","warn","info","debug"],format:r?a.combine(a.colorize(),a.timestamp({format:"HH:mm:ss"}),a.printf(({timestamp:i,level:s,message:o,service:n,requestId:l,...g})=>{let f=Object.keys(g).length?` ${JSON.stringify(g)}`:"",w=l?` [${l}]`:"";return`${i} ${s}${w}: ${o}${f}`})):a.json()})]}),t==="production"&&(this.logger.add(new y.File({filename:"logs/error.log",level:"error",maxsize:10*1024*1024,maxFiles:5})),this.logger.add(new y.File({filename:"logs/combined.log",maxsize:10*1024*1024,maxFiles:10})))}setRequestContext(e){this.requestContext=e}clearRequestContext(){this.requestContext=void 0}formatMessage(e,t){let r={...t,requestId:t?.requestId||this.requestContext?.requestId,timestamp:new Date().toISOString()};return this.requestContext?.startTime&&!r.duration&&(r.duration=Date.now()-this.requestContext.startTime),[e,r]}debug(e,t){let[r,i]=this.formatMessage(e,t);this.logger.debug(r,i)}info(e,t){let[r,i]=this.formatMessage(e,t);this.logger.info(r,i)}warn(e,t){let[r,i]=this.formatMessage(e,t);this.logger.warn(r,i)}error(e,t,r){let[i,s]=this.formatMessage(e,r),o={...s,...t&&{error:{name:t.name,message:t.message,stack:t.stack,...t.constructor.name!=="Error"&&{type:t.constructor.name}}}};this.logger.error(i,o)}mcpRequest(e,t,r){this.info("MCP request received",{...r,method:e,params:t?JSON.stringify(t):void 0})}mcpResponse(e,t,r,i){let s=`MCP request ${t?"completed":"failed"}`,o={...i,method:e,success:t,duration:r};t?this.info(s,o):this.warn(s,o)}serverEvent(e,t,r){this.info(`Server event: ${e}`,{...r,event:e,details:t?JSON.stringify(t):void 0})}performanceMetric(e,t,r,i){this.info(`Performance: ${e}`,{...i,operation:e,duration:t,...r})}child(e){let t=new u;return t.logger=this.logger.child(e),t.requestContext=this.requestContext,t}},v;function q(){return v||(v=new c),v}var z=q();import x from"axios";var p=class{logger;cache;accessOrder;maxSize;defaultTTL;constructor(e=1e3,t=3e5){this.logger=new c("ResponseCache"),this.cache=new Map,this.accessOrder=[],this.maxSize=e,this.defaultTTL=t}generateKey(e,t,r){let i=`${e}:${t}`;if(r){let s=JSON.stringify(r,Object.keys(r).sort());return`${i}:${s}`}return i}get(e,t,r){let i=this.generateKey(e,t,r),s=this.cache.get(i);return s?Date.now()-s.timestamp>s.ttl?(this.logger.debug("Cache expired",{key:i}),this.cache.delete(i),this.accessOrder=this.accessOrder.filter(n=>n!==i),null):(this.updateAccessOrder(i),this.logger.debug("Cache hit",{key:i}),s.data):(this.logger.debug("Cache miss",{key:i}),null)}set(e,t,r,i,s){let o=this.generateKey(e,t,i);this.cache.size>=this.maxSize&&!this.cache.has(o)&&this.evictLRU();let n={data:r,timestamp:Date.now(),ttl:s||this.defaultTTL};this.cache.set(o,n),this.updateAccessOrder(o),this.logger.debug("Cache set",{key:o,ttl:n.ttl})}invalidate(e){let t=0,r=new RegExp(e);for(let i of this.cache.keys())r.test(i)&&(this.cache.delete(i),this.accessOrder=this.accessOrder.filter(s=>s!==i),t++);return this.logger.info("Cache invalidated",{pattern:e,count:t}),t}clear(){let e=this.cache.size;this.cache.clear(),this.accessOrder=[],this.logger.info("Cache cleared",{size:e})}getStats(){return{size:this.cache.size,maxSize:this.maxSize,hitRate:0}}updateAccessOrder(e){this.accessOrder=this.accessOrder.filter(t=>t!==e),this.accessOrder.push(e)}evictLRU(){if(this.accessOrder.length===0)return;let e=this.accessOrder.shift();this.cache.delete(e),this.logger.debug("LRU eviction",{key:e})}cleanup(){let e=Date.now(),t=0;for(let[r,i]of this.cache.entries())e-i.timestamp>i.ttl&&(this.cache.delete(r),this.accessOrder=this.accessOrder.filter(s=>s!==r),t++);return t>0&&this.logger.debug("Cache cleanup",{removed:t}),t}};import{v4 as S}from"uuid";var d=class{logger;queue;maxSize;maxRetries;isProcessing;processCallback;constructor(e=100,t=3){this.logger=new c("OfflineQueue"),this.queue=[],this.maxSize=e,this.maxRetries=t,this.isProcessing=!1}setProcessCallback(e){this.processCallback=e}enqueue(e,t,r){if(this.queue.length>=this.maxSize){let s=this.queue.shift();this.logger.warn("Queue full, removed oldest request",{removed:s})}let i={id:S(),method:e,endpoint:t,data:r,timestamp:Date.now(),retries:0};return this.queue.push(i),this.logger.info("Request queued",{id:i.id,method:e,endpoint:t,queueSize:this.queue.length}),i.id}async processQueue(){if(this.isProcessing){this.logger.debug("Queue already processing");return}if(this.queue.length===0){this.logger.debug("Queue empty");return}if(!this.processCallback){this.logger.error("No process callback set");return}this.isProcessing=!0,this.logger.info("Processing queue",{queueSize:this.queue.length});let e=[],t=[];for(let r of this.queue)try{await this.processCallback(r),e.push(r.id),this.logger.info("Request processed",{id:r.id})}catch(i){this.logger.error("Failed to process request",i instanceof Error?i:new Error(String(i)),{id:r.id,retries:r.retries}),r.retries++,r.retries<this.maxRetries?t.push(r):this.logger.error("Request exceeded max retries, discarding",new Error("Max retries exceeded"),{id:r.id,maxRetries:this.maxRetries})}this.queue=t,this.logger.info("Queue processing complete",{processed:e.length,failed:t.length}),this.isProcessing=!1}getStatus(){return{size:this.queue.length,maxSize:this.maxSize,isProcessing:this.isProcessing,oldestTimestamp:this.queue[0]?.timestamp}}clear(){let e=this.queue.length;this.queue=[],this.logger.info("Queue cleared",{size:e})}getQueue(){return[...this.queue]}remove(e){let t=this.queue.length;this.queue=this.queue.filter(i=>i.id!==e);let r=this.queue.length<t;return r&&this.logger.info("Request removed from queue",{requestId:e}),r}};var m=class{logger;config;http;cache;offlineQueue;isOnline;constructor(e){this.logger=new c("TimofiAPIClient"),this.config={apiUrl:e.apiUrl,apiKey:e.apiKey,timeout:e.timeout||3e4,retries:e.retries||3,retryDelay:e.retryDelay||1e3,cacheEnabled:e.cacheEnabled!==!1,cacheTTL:e.cacheTTL||3e5,offlineQueueEnabled:e.offlineQueueEnabled!==!1,http2:e.http2||!1},this.http=x.create({baseURL:this.config.apiUrl,timeout:this.config.timeout,headers:{Authorization:`Bearer ${this.config.apiKey}`,"Content-Type":"application/json"}}),this.cache=new p(1e3,this.config.cacheTTL),this.offlineQueue=new d(100,this.config.retries),this.offlineQueue.setProcessCallback(async t=>{await this.requestWithRetry(t.method,t.endpoint,t.data,1,!1)}),this.isOnline=!0,setInterval(()=>this.cache.cleanup(),6e4),this.logger.info("API client initialized",{apiUrl:this.config.apiUrl,cacheEnabled:this.config.cacheEnabled,offlineQueueEnabled:this.config.offlineQueueEnabled})}async storeMemory(e){return this.post("/api/v1/memories",e)}async searchMemories(e){let t=`search:${e.repository}:${e.query}`;return this.get("/api/v1/memories",e,t)}async getMemory(e){return this.get(`/api/v1/memories/${e}`)}async deleteMemory(e){await this.delete(`/api/v1/memories/${e}`)}async searchCode(e){let t=`code:${e.repository}:${e.query}`,r={repository:e.repository,q:e.query,language:e.language,path:e.path,limit:e.limit};return this.get("/api/v1/code/search",r,t)}async getFileContext(e){let t=`file:${e.repository}:${e.filePath}`;return this.get(`/api/v1/code/files/${encodeURIComponent(e.filePath)}`,{repository:e.repository,lineStart:e.lineStart,lineEnd:e.lineEnd},t)}async getProjectOverview(e){let t=`overview:${e.repository}`;return this.get("/api/v1/code/overview",{repository:e.repository},t)}async getSymbolInfo(e,t){return this.get(`/api/v1/code/symbols/${e}`,{repository:t})}async getSymbolReferences(e,t){return this.get(`/api/v1/code/symbols/${e}/references`,{repository:t})}async startIndexing(e){return this.post(`/api/v1/repositories/${e.owner}/${e.repo}/index`,{incremental:e.incremental,options:{branch:e.branch}})}async getRepository(e,t){return this.get(`/api/v1/repositories/${e}/${t}`)}async getIndexingTask(e){return this.get(`/api/v1/workers/tasks/${e.taskId}`)}async cancelIndexingTask(e){await this.delete(`/api/v1/workers/tasks/${e}`)}async listRepositories(){return this.get("/api/v1/repositories")}async get(e,t,r){if(this.config.cacheEnabled&&r){let s=this.cache.get("GET",e,t);if(s)return s}let i=await this.requestWithRetry("GET",e,t);return this.config.cacheEnabled&&r&&this.cache.set("GET",e,i,t),i}async post(e,t){return this.requestWithRetry("POST",e,t)}async delete(e){await this.requestWithRetry("DELETE",e)}async requestWithRetry(e,t,r,i=1,s=!0){try{let o={method:e,url:t};e==="GET"&&r?o.params=r:r&&(o.data=r);let n=await this.http.request(o);if(this.isOnline||(this.isOnline=!0,this.logger.info("API connection restored"),this.config.offlineQueueEnabled&&await this.offlineQueue.processQueue()),!n.data.success)throw new h(n.data.error||{message:"Unknown error"});return n.data.data}catch(o){if(x.isAxiosError(o)){let n=o;if(!n.response){if(this.logger.error("Network error",o,{endpoint:t,attempt:i}),this.isOnline&&(this.isOnline=!1,this.logger.warn("API connection lost")),s&&this.config.offlineQueueEnabled&&i===1)throw this.offlineQueue.enqueue(e,t,r),new Error("Request queued due to network error");if(i<this.config.retries){let l=Math.min(this.config.retryDelay*Math.pow(2,i-1),1e4);return this.logger.info("Retrying request",{endpoint:t,attempt:i,delay:l}),await this.sleep(l),this.requestWithRetry(e,t,r,i+1,!1)}throw new Error(`Network error after ${i} attempts`)}if(n.response.status===429){let l=n.response.data.error?.retryAfter||6e4;if(this.logger.warn("Rate limit exceeded",{endpoint:t,retryAfter:l}),i<this.config.retries)return await this.sleep(l),this.requestWithRetry(e,t,r,i+1,!1);throw new Error("Rate limit exceeded")}if(n.response.data?.error)throw new h(n.response.data.error)}throw this.logger.error("Request failed",o instanceof Error?o:void 0,{endpoint:t,attempt:i}),o}}sleep(e){return new Promise(t=>setTimeout(t,e))}invalidateCache(e){return this.cache.invalidate(e)}clearCache(){this.cache.clear()}getCacheStats(){return this.cache.getStats()}getQueueStatus(){return this.offlineQueue.getStatus()}async processOfflineQueue(){await this.offlineQueue.processQueue()}clearQueue(){this.offlineQueue.clear()}async healthCheck(){try{return await this.http.get("/health"),!0}catch{return!1}}},h=class extends Error{type;details;requestId;constructor(e){super(e.message||"API error"),this.name="APIClientError",this.type=e.type||"unknown_error",this.details=e.details,this.requestId=e.requestId}};var R=class extends L{server;transport;state="starting";logger;config;apiClient;startTime;shutdownTimer;activeRequests=new Map;processHandlers=[];constructor(e){super(),this.config={...e,environment:e.environment||"development",shutdownTimeout:e.shutdownTimeout||5e3},this.logger=new c("TimofiMCPClient"),this.startTime=new Date;let t={apiUrl:this.config.apiUrl,apiKey:this.config.apiKey,cacheEnabled:this.config.cacheEnabled,cacheTTL:this.config.cacheTTL,offlineQueueEnabled:this.config.offlineQueueEnabled};this.apiClient=new m(t),this.server=new T({name:e.name,version:e.version}),this.setupServerHandlers(),this.setupProcessHandlers()}setupServerHandlers(){this.server.setRequestHandler(P,async e=>{let t=this.generateRequestId(),r=this.createRequestContext(t,"initialize",e.params);this.logger.info("Initialize request",{params:e.params});try{let i={protocolVersion:"2024-11-05",capabilities:{tools:{},resources:{},prompts:{}},serverInfo:{name:this.config.name,version:this.config.version}};return this.logger.info("Initialize response",{duration:Date.now()-r.startTime}),i}catch(i){throw this.logger.error("Initialize request failed",i),i}finally{this.activeRequests.delete(t)}}),this.server.setRequestHandler(I,async()=>{let e=this.generateRequestId(),t=this.createRequestContext(e,"tools/list");this.logger.info("Tools list request");try{let r=this.getToolsList();return this.logger.info("Tools list response",{count:r.length,duration:Date.now()-t.startTime}),{tools:r}}catch(r){throw this.logger.error("Tools list request failed",r),r}finally{this.activeRequests.delete(e)}}),this.server.setRequestHandler(E,async()=>{let e=this.generateRequestId(),t=this.createRequestContext(e,"resources/list");this.logger.info("Resources list request");try{let r=[];return this.logger.info("Resources list response",{duration:Date.now()-t.startTime}),{resources:r}}catch(r){throw this.logger.error("Resources list request failed",r),r}finally{this.activeRequests.delete(e)}}),this.server.setRequestHandler(O,async()=>({status:"pong",timestamp:new Date().toISOString(),server:this.config.name,version:this.config.version})),this.server.setRequestHandler(k,async e=>{let t=this.generateRequestId(),r=this.createRequestContext(t,"tools/call",e.params);this.logger.info("Tool call request",{tool:e.params.name,args:e.params.arguments});try{let i=await this.handleToolCall(e.params.name,e.params.arguments||{});return this.logger.info("Tool call response",{tool:e.params.name,duration:Date.now()-r.startTime}),i}catch(i){throw this.logger.error("Tool call request failed",i,{tool:e.params.name}),i instanceof h?new Error(`API Error: ${i.message}`):i}finally{this.activeRequests.delete(t)}}),this.server.onerror=e=>{this.logger.error("MCP Server error",e),this.emit("error",{error:e}),this.state!=="shutting_down"&&this.setState("error")},this.logger.debug("MCP protocol handlers initialized")}setupProcessHandlers(){let e=()=>this.shutdown("SIGTERM"),t=()=>this.shutdown("SIGINT"),r=s=>{this.logger.error("Uncaught exception",s),this.shutdown("uncaught_exception")},i=s=>{this.logger.error("Unhandled rejection",s),this.shutdown("unhandled_rejection")};process.on("SIGTERM",e),process.on("SIGINT",t),process.on("uncaughtException",r),process.on("unhandledRejection",i),this.processHandlers=[{event:"SIGTERM",handler:e},{event:"SIGINT",handler:t},{event:"uncaughtException",handler:r},{event:"unhandledRejection",handler:i}]}cleanupProcessHandlers(){for(let{event:e,handler:t}of this.processHandlers)process.removeListener(e,t);this.processHandlers=[]}getToolsList(){return[{name:"store_memory",description:"Store a new memory in the context store for a repository",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},content:{type:"string",description:"Content to remember"},context:{type:"object",description:"Additional context information"},metadata:{type:"object",description:"Additional metadata"}},required:["repository","content"]}},{name:"search_memories",description:"Search for memories related to a query",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},query:{type:"string",description:"Search query"},limit:{type:"number",description:"Maximum number of results"},threshold:{type:"number",description:"Similarity threshold (0-1)"}},required:["repository","query"]}},{name:"search_code",description:"Search for code patterns across repository files",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},query:{type:"string",description:"Search query"},language:{type:"string",description:"Filter by programming language"},path:{type:"string",description:"Filter by file path pattern"},limit:{type:"number",description:"Maximum number of results"}},required:["repository","query"]}},{name:"get_file_context",description:"Get the context of a specific file with symbols and structure",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},filePath:{type:"string",description:"Path to the file"},lineStart:{type:"number",description:"Starting line number"},lineEnd:{type:"number",description:"Ending line number"}},required:["repository","filePath"]}},{name:"get_project_overview",description:"Get project overview: file tree structure, README, and key docs (CONTRIBUTING, LICENSE, etc.). Use this to understand the repository layout and documentation before searching code.",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"}},required:["repository"]}},{name:"list_repositories",description:"List all available repositories that have been connected and indexed",inputSchema:{type:"object",properties:{}}},{name:"start_indexing",description:"Start indexing a repository",inputSchema:{type:"object",properties:{owner:{type:"string",description:"Repository owner"},repo:{type:"string",description:"Repository name"},incremental:{type:"boolean",description:"Perform incremental indexing"},branch:{type:"string",description:"Branch to index"}},required:["owner","repo"]}},{name:"get_indexing_status",description:"Get the status of a repository indexing task",inputSchema:{type:"object",properties:{taskId:{type:"string",description:"Indexing task ID"}},required:["taskId"]}}]}async handleToolCall(e,t){switch(e){case"store_memory":return{content:[{type:"text",text:`Memory stored successfully with ID: ${(await this.apiClient.storeMemory({repository:t.repository,content:t.content,context:t.context,metadata:t.metadata})).memoryId}`}]};case"search_memories":let i=await this.apiClient.searchMemories({repository:t.repository,query:t.query,limit:t.limit,threshold:t.threshold});return{content:[{type:"text",text:JSON.stringify(i,null,2)}]};case"search_code":let s=await this.apiClient.searchCode({repository:t.repository,query:t.query,language:t.language,path:t.path,limit:t.limit});return{content:[{type:"text",text:JSON.stringify(s,null,2)}]};case"get_file_context":let o=await this.apiClient.getFileContext({repository:t.repository,filePath:t.filePath,lineStart:t.lineStart,lineEnd:t.lineEnd});return{content:[{type:"text",text:JSON.stringify(o,null,2)}]};case"get_project_overview":let n=await this.apiClient.getProjectOverview({repository:t.repository});return{content:[{type:"text",text:JSON.stringify(n,null,2)}]};case"list_repositories":let l=await this.apiClient.listRepositories();return{content:[{type:"text",text:JSON.stringify(l,null,2)}]};case"start_indexing":let g=await this.apiClient.startIndexing({owner:t.owner,repo:t.repo,incremental:t.incremental,branch:t.branch});return{content:[{type:"text",text:`Indexing started. Task ID: ${g.taskId}, Status: ${g.status}`}]};case"get_indexing_status":let f=await this.apiClient.getIndexingTask({taskId:t.taskId});return{content:[{type:"text",text:JSON.stringify(f,null,2)}]};default:throw new Error(`Unknown tool: ${e}`)}}generateRequestId(){return M()}createRequestContext(e,t,r){let i={requestId:e,timestamp:new Date,method:t,params:r,startTime:Date.now()};return this.activeRequests.set(e,i),i}setState(e){let t=this.state;this.state=e,this.logger.info("State change",{from:t,to:e})}async start(){try{if(this.setState("starting"),this.logger.info("Starting Timofi MCP Client",{name:this.config.name,version:this.config.version,apiUrl:this.config.apiUrl}),!await this.apiClient.healthCheck())throw new Error("API server is not accessible");this.transport=new b,await this.server.connect(this.transport),this.setState("ready"),this.logger.info("Timofi MCP Client started successfully"),this.emit("started",{config:this.config}),this.emit("ready",{uptime:this.getUptime()})}catch(e){throw this.setState("error"),this.logger.error("Failed to start MCP Client",e),this.emit("error",{error:e}),e}}async shutdown(e="manual"){if(this.state==="shutting_down"||this.state==="stopped")return;this.setState("shutting_down"),this.logger.info(`Shutting down client (reason: ${e})`);let t=new Promise(r=>{this.shutdownTimer=setTimeout(()=>{this.logger.warn("Forced shutdown after timeout"),r()},this.config.shutdownTimeout)});try{await Promise.race([this.waitForActiveRequests(),t]),await this.apiClient.processOfflineQueue(),this.server&&this.transport&&await this.server.close(),this.cleanupProcessHandlers(),this.setState("stopped"),this.logger.info("Client shutdown completed"),this.emit("shutdown",{reason:e})}catch(r){this.logger.error("Error during shutdown",r),this.setState("error"),this.emit("error",{error:r})}finally{this.shutdownTimer&&clearTimeout(this.shutdownTimer)}}async waitForActiveRequests(){let r=0;for(;this.activeRequests.size>0&&r<3e3;)await new Promise(i=>setTimeout(i,100)),r+=100;this.activeRequests.size>0&&this.logger.warn(`${this.activeRequests.size} requests still active during shutdown`)}getState(){return this.state}getUptime(){return Date.now()-this.startTime.getTime()}getConfig(){return{...this.config}}getActiveRequestsCount(){return this.activeRequests.size}getCacheStats(){return this.apiClient.getCacheStats()}getQueueStatus(){return this.apiClient.getQueueStatus()}invalidateCache(e){return this.apiClient.invalidateCache(e)}};export{R as TimofiMCPClient};

package/dist/mcp-client-cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import{Server as I}from"@modelcontextprotocol/sdk/server/index.js";import{StdioServerTransport as E}from"@modelcontextprotocol/sdk/server/stdio.js";import{InitializeRequestSchema as O,ListToolsRequestSchema as M,ListResourcesRequestSchema as L,PingRequestSchema as k,CallToolRequestSchema as A}from"@modelcontextprotocol/sdk/types.js";import{EventEmitter as _}from"events";import{randomUUID as Q}from"crypto";import{createLogger as S,format as l,transports as C}from"winston";var c=class n{logger;requestContext;constructor(e="info",t="development"){let r=t==="development";this.logger=S({level:e,format:l.combine(l.timestamp(),l.errors({stack:!0}),l.json(),r?l.prettyPrint():l.uncolorize()),defaultMeta:{service:"timofi-context-server",version:process.env.npm_package_version||"1.0.0"},transports:[new C.Console({stderrLevels:["error","warn","info","debug"],format:r?l.combine(l.colorize(),l.timestamp({format:"HH:mm:ss"}),l.printf(({timestamp:i,level:s,message:o,service:a,requestId:u,...p})=>{let v=Object.keys(p).length?` ${JSON.stringify(p)}`:"",q=u?` [${u}]`:"";return`${i} ${s}${q}: ${o}${v}`})):l.json()})]}),t==="production"&&(this.logger.add(new C.File({filename:"logs/error.log",level:"error",maxsize:10*1024*1024,maxFiles:5})),this.logger.add(new C.File({filename:"logs/combined.log",maxsize:10*1024*1024,maxFiles:10})))}setRequestContext(e){this.requestContext=e}clearRequestContext(){this.requestContext=void 0}formatMessage(e,t){let r={...t,requestId:t?.requestId||this.requestContext?.requestId,timestamp:new Date().toISOString()};return this.requestContext?.startTime&&!r.duration&&(r.duration=Date.now()-this.requestContext.startTime),[e,r]}debug(e,t){let[r,i]=this.formatMessage(e,t);this.logger.debug(r,i)}info(e,t){let[r,i]=this.formatMessage(e,t);this.logger.info(r,i)}warn(e,t){let[r,i]=this.formatMessage(e,t);this.logger.warn(r,i)}error(e,t,r){let[i,s]=this.formatMessage(e,r),o={...s,...t&&{error:{name:t.name,message:t.message,stack:t.stack,...t.constructor.name!=="Error"&&{type:t.constructor.name}}}};this.logger.error(i,o)}mcpRequest(e,t,r){this.info("MCP request received",{...r,method:e,params:t?JSON.stringify(t):void 0})}mcpResponse(e,t,r,i){let s=`MCP request ${t?"completed":"failed"}`,o={...i,method:e,success:t,duration:r};t?this.info(s,o):this.warn(s,o)}serverEvent(e,t,r){this.info(`Server event: ${e}`,{...r,event:e,details:t?JSON.stringify(t):void 0})}performanceMetric(e,t,r,i){this.info(`Performance: ${e}`,{...i,operation:e,duration:t,...r})}child(e){let t=new n;return t.logger=this.logger.child(e),t.requestContext=this.requestContext,t}},x;function P(){return x||(x=new c),x}var G=P();import R from"axios";var d=class{logger;cache;accessOrder;maxSize;defaultTTL;constructor(e=1e3,t=3e5){this.logger=new c("ResponseCache"),this.cache=new Map,this.accessOrder=[],this.maxSize=e,this.defaultTTL=t}generateKey(e,t,r){let i=`${e}:${t}`;if(r){let s=JSON.stringify(r,Object.keys(r).sort());return`${i}:${s}`}return i}get(e,t,r){let i=this.generateKey(e,t,r),s=this.cache.get(i);return s?Date.now()-s.timestamp>s.ttl?(this.logger.debug("Cache expired",{key:i}),this.cache.delete(i),this.accessOrder=this.accessOrder.filter(a=>a!==i),null):(this.updateAccessOrder(i),this.logger.debug("Cache hit",{key:i}),s.data):(this.logger.debug("Cache miss",{key:i}),null)}set(e,t,r,i,s){let o=this.generateKey(e,t,i);this.cache.size>=this.maxSize&&!this.cache.has(o)&&this.evictLRU();let a={data:r,timestamp:Date.now(),ttl:s||this.defaultTTL};this.cache.set(o,a),this.updateAccessOrder(o),this.logger.debug("Cache set",{key:o,ttl:a.ttl})}invalidate(e){let t=0,r=new RegExp(e);for(let i of this.cache.keys())r.test(i)&&(this.cache.delete(i),this.accessOrder=this.accessOrder.filter(s=>s!==i),t++);return this.logger.info("Cache invalidated",{pattern:e,count:t}),t}clear(){let e=this.cache.size;this.cache.clear(),this.accessOrder=[],this.logger.info("Cache cleared",{size:e})}getStats(){return{size:this.cache.size,maxSize:this.maxSize,hitRate:0}}updateAccessOrder(e){this.accessOrder=this.accessOrder.filter(t=>t!==e),this.accessOrder.push(e)}evictLRU(){if(this.accessOrder.length===0)return;let e=this.accessOrder.shift();this.cache.delete(e),this.logger.debug("LRU eviction",{key:e})}cleanup(){let e=Date.now(),t=0;for(let[r,i]of this.cache.entries())e-i.timestamp>i.ttl&&(this.cache.delete(r),this.accessOrder=this.accessOrder.filter(s=>s!==r),t++);return t>0&&this.logger.debug("Cache cleanup",{removed:t}),t}};import{v4 as b}from"uuid";var m=class{logger;queue;maxSize;maxRetries;isProcessing;processCallback;constructor(e=100,t=3){this.logger=new c("OfflineQueue"),this.queue=[],this.maxSize=e,this.maxRetries=t,this.isProcessing=!1}setProcessCallback(e){this.processCallback=e}enqueue(e,t,r){if(this.queue.length>=this.maxSize){let s=this.queue.shift();this.logger.warn("Queue full, removed oldest request",{removed:s})}let i={id:b(),method:e,endpoint:t,data:r,timestamp:Date.now(),retries:0};return this.queue.push(i),this.logger.info("Request queued",{id:i.id,method:e,endpoint:t,queueSize:this.queue.length}),i.id}async processQueue(){if(this.isProcessing){this.logger.debug("Queue already processing");return}if(this.queue.length===0){this.logger.debug("Queue empty");return}if(!this.processCallback){this.logger.error("No process callback set");return}this.isProcessing=!0,this.logger.info("Processing queue",{queueSize:this.queue.length});let e=[],t=[];for(let r of this.queue)try{await this.processCallback(r),e.push(r.id),this.logger.info("Request processed",{id:r.id})}catch(i){this.logger.error("Failed to process request",i instanceof Error?i:new Error(String(i)),{id:r.id,retries:r.retries}),r.retries++,r.retries<this.maxRetries?t.push(r):this.logger.error("Request exceeded max retries, discarding",new Error("Max retries exceeded"),{id:r.id,maxRetries:this.maxRetries})}this.queue=t,this.logger.info("Queue processing complete",{processed:e.length,failed:t.length}),this.isProcessing=!1}getStatus(){return{size:this.queue.length,maxSize:this.maxSize,isProcessing:this.isProcessing,oldestTimestamp:this.queue[0]?.timestamp}}clear(){let e=this.queue.length;this.queue=[],this.logger.info("Queue cleared",{size:e})}getQueue(){return[...this.queue]}remove(e){let t=this.queue.length;this.queue=this.queue.filter(i=>i.id!==e);let r=this.queue.length<t;return r&&this.logger.info("Request removed from queue",{requestId:e}),r}};var f=class{logger;config;http;cache;offlineQueue;isOnline;constructor(e){this.logger=new c("TimofiAPIClient"),this.config={apiUrl:e.apiUrl,apiKey:e.apiKey,timeout:e.timeout||3e4,retries:e.retries||3,retryDelay:e.retryDelay||1e3,cacheEnabled:e.cacheEnabled!==!1,cacheTTL:e.cacheTTL||3e5,offlineQueueEnabled:e.offlineQueueEnabled!==!1,http2:e.http2||!1},this.http=R.create({baseURL:this.config.apiUrl,timeout:this.config.timeout,headers:{Authorization:`Bearer ${this.config.apiKey}`,"Content-Type":"application/json"}}),this.cache=new d(1e3,this.config.cacheTTL),this.offlineQueue=new m(100,this.config.retries),this.offlineQueue.setProcessCallback(async t=>{await this.requestWithRetry(t.method,t.endpoint,t.data,1,!1)}),this.isOnline=!0,setInterval(()=>this.cache.cleanup(),6e4),this.logger.info("API client initialized",{apiUrl:this.config.apiUrl,cacheEnabled:this.config.cacheEnabled,offlineQueueEnabled:this.config.offlineQueueEnabled})}async storeMemory(e){return this.post("/api/v1/memories",e)}async searchMemories(e){let t=`search:${e.repository}:${e.query}`;return this.get("/api/v1/memories",e,t)}async getMemory(e){return this.get(`/api/v1/memories/${e}`)}async deleteMemory(e){await this.delete(`/api/v1/memories/${e}`)}async searchCode(e){let t=`code:${e.repository}:${e.query}`,r={repository:e.repository,q:e.query,language:e.language,path:e.path,limit:e.limit};return this.get("/api/v1/code/search",r,t)}async getFileContext(e){let t=`file:${e.repository}:${e.filePath}`;return this.get(`/api/v1/code/files/${encodeURIComponent(e.filePath)}`,{repository:e.repository,lineStart:e.lineStart,lineEnd:e.lineEnd},t)}async getProjectOverview(e){let t=`overview:${e.repository}`;return this.get("/api/v1/code/overview",{repository:e.repository},t)}async getSymbolInfo(e,t){return this.get(`/api/v1/code/symbols/${e}`,{repository:t})}async getSymbolReferences(e,t){return this.get(`/api/v1/code/symbols/${e}/references`,{repository:t})}async startIndexing(e){return this.post(`/api/v1/repositories/${e.owner}/${e.repo}/index`,{incremental:e.incremental,options:{branch:e.branch}})}async getRepository(e,t){return this.get(`/api/v1/repositories/${e}/${t}`)}async getIndexingTask(e){return this.get(`/api/v1/workers/tasks/${e.taskId}`)}async cancelIndexingTask(e){await this.delete(`/api/v1/workers/tasks/${e}`)}async listRepositories(){return this.get("/api/v1/repositories")}async get(e,t,r){if(this.config.cacheEnabled&&r){let s=this.cache.get("GET",e,t);if(s)return s}let i=await this.requestWithRetry("GET",e,t);return this.config.cacheEnabled&&r&&this.cache.set("GET",e,i,t),i}async post(e,t){return this.requestWithRetry("POST",e,t)}async delete(e){await this.requestWithRetry("DELETE",e)}async requestWithRetry(e,t,r,i=1,s=!0){try{let o={method:e,url:t};e==="GET"&&r?o.params=r:r&&(o.data=r);let a=await this.http.request(o);if(this.isOnline||(this.isOnline=!0,this.logger.info("API connection restored"),this.config.offlineQueueEnabled&&await this.offlineQueue.processQueue()),!a.data.success)throw new g(a.data.error||{message:"Unknown error"});return a.data.data}catch(o){if(R.isAxiosError(o)){let a=o;if(!a.response){if(this.logger.error("Network error",o,{endpoint:t,attempt:i}),this.isOnline&&(this.isOnline=!1,this.logger.warn("API connection lost")),s&&this.config.offlineQueueEnabled&&i===1)throw this.offlineQueue.enqueue(e,t,r),new Error("Request queued due to network error");if(i<this.config.retries){let u=Math.min(this.config.retryDelay*Math.pow(2,i-1),1e4);return this.logger.info("Retrying request",{endpoint:t,attempt:i,delay:u}),await this.sleep(u),this.requestWithRetry(e,t,r,i+1,!1)}throw new Error(`Network error after ${i} attempts`)}if(a.response.status===429){let u=a.response.data.error?.retryAfter||6e4;if(this.logger.warn("Rate limit exceeded",{endpoint:t,retryAfter:u}),i<this.config.retries)return await this.sleep(u),this.requestWithRetry(e,t,r,i+1,!1);throw new Error("Rate limit exceeded")}if(a.response.data?.error)throw new g(a.response.data.error)}throw this.logger.error("Request failed",o instanceof Error?o:void 0,{endpoint:t,attempt:i}),o}}sleep(e){return new Promise(t=>setTimeout(t,e))}invalidateCache(e){return this.cache.invalidate(e)}clearCache(){this.cache.clear()}getCacheStats(){return this.cache.getStats()}getQueueStatus(){return this.offlineQueue.getStatus()}async processOfflineQueue(){await this.offlineQueue.processQueue()}clearQueue(){this.offlineQueue.clear()}async healthCheck(){try{return await this.http.get("/health"),!0}catch{return!1}}},g=class extends Error{type;details;requestId;constructor(e){super(e.message||"API error"),this.name="APIClientError",this.type=e.type||"unknown_error",this.details=e.details,this.requestId=e.requestId}};var y=class extends _{server;transport;state="starting";logger;config;apiClient;startTime;shutdownTimer;activeRequests=new Map;processHandlers=[];constructor(e){super(),this.config={...e,environment:e.environment||"development",shutdownTimeout:e.shutdownTimeout||5e3},this.logger=new c("TimofiMCPClient"),this.startTime=new Date;let t={apiUrl:this.config.apiUrl,apiKey:this.config.apiKey,cacheEnabled:this.config.cacheEnabled,cacheTTL:this.config.cacheTTL,offlineQueueEnabled:this.config.offlineQueueEnabled};this.apiClient=new f(t),this.server=new I({name:e.name,version:e.version}),this.setupServerHandlers(),this.setupProcessHandlers()}setupServerHandlers(){this.server.setRequestHandler(O,async e=>{let t=this.generateRequestId(),r=this.createRequestContext(t,"initialize",e.params);this.logger.info("Initialize request",{params:e.params});try{let i={protocolVersion:"2024-11-05",capabilities:{tools:{},resources:{},prompts:{}},serverInfo:{name:this.config.name,version:this.config.version}};return this.logger.info("Initialize response",{duration:Date.now()-r.startTime}),i}catch(i){throw this.logger.error("Initialize request failed",i),i}finally{this.activeRequests.delete(t)}}),this.server.setRequestHandler(M,async()=>{let e=this.generateRequestId(),t=this.createRequestContext(e,"tools/list");this.logger.info("Tools list request");try{let r=this.getToolsList();return this.logger.info("Tools list response",{count:r.length,duration:Date.now()-t.startTime}),{tools:r}}catch(r){throw this.logger.error("Tools list request failed",r),r}finally{this.activeRequests.delete(e)}}),this.server.setRequestHandler(L,async()=>{let e=this.generateRequestId(),t=this.createRequestContext(e,"resources/list");this.logger.info("Resources list request");try{let r=[];return this.logger.info("Resources list response",{duration:Date.now()-t.startTime}),{resources:r}}catch(r){throw this.logger.error("Resources list request failed",r),r}finally{this.activeRequests.delete(e)}}),this.server.setRequestHandler(k,async()=>({status:"pong",timestamp:new Date().toISOString(),server:this.config.name,version:this.config.version})),this.server.setRequestHandler(A,async e=>{let t=this.generateRequestId(),r=this.createRequestContext(t,"tools/call",e.params);this.logger.info("Tool call request",{tool:e.params.name,args:e.params.arguments});try{let i=await this.handleToolCall(e.params.name,e.params.arguments||{});return this.logger.info("Tool call response",{tool:e.params.name,duration:Date.now()-r.startTime}),i}catch(i){throw this.logger.error("Tool call request failed",i,{tool:e.params.name}),i instanceof g?new Error(`API Error: ${i.message}`):i}finally{this.activeRequests.delete(t)}}),this.server.onerror=e=>{this.logger.error("MCP Server error",e),this.emit("error",{error:e}),this.state!=="shutting_down"&&this.setState("error")},this.logger.debug("MCP protocol handlers initialized")}setupProcessHandlers(){let e=()=>this.shutdown("SIGTERM"),t=()=>this.shutdown("SIGINT"),r=s=>{this.logger.error("Uncaught exception",s),this.shutdown("uncaught_exception")},i=s=>{this.logger.error("Unhandled rejection",s),this.shutdown("unhandled_rejection")};process.on("SIGTERM",e),process.on("SIGINT",t),process.on("uncaughtException",r),process.on("unhandledRejection",i),this.processHandlers=[{event:"SIGTERM",handler:e},{event:"SIGINT",handler:t},{event:"uncaughtException",handler:r},{event:"unhandledRejection",handler:i}]}cleanupProcessHandlers(){for(let{event:e,handler:t}of this.processHandlers)process.removeListener(e,t);this.processHandlers=[]}getToolsList(){return[{name:"store_memory",description:"Store a new memory in the context store for a repository",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},content:{type:"string",description:"Content to remember"},context:{type:"object",description:"Additional context information"},metadata:{type:"object",description:"Additional metadata"}},required:["repository","content"]}},{name:"search_memories",description:"Search for memories related to a query",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},query:{type:"string",description:"Search query"},limit:{type:"number",description:"Maximum number of results"},threshold:{type:"number",description:"Similarity threshold (0-1)"}},required:["repository","query"]}},{name:"search_code",description:"Search for code patterns across repository files",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},query:{type:"string",description:"Search query"},language:{type:"string",description:"Filter by programming language"},path:{type:"string",description:"Filter by file path pattern"},limit:{type:"number",description:"Maximum number of results"}},required:["repository","query"]}},{name:"get_file_context",description:"Get the context of a specific file with symbols and structure",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"},filePath:{type:"string",description:"Path to the file"},lineStart:{type:"number",description:"Starting line number"},lineEnd:{type:"number",description:"Ending line number"}},required:["repository","filePath"]}},{name:"get_project_overview",description:"Get project overview: file tree structure, README, and key docs (CONTRIBUTING, LICENSE, etc.). Use this to understand the repository layout and documentation before searching code.",inputSchema:{type:"object",properties:{repository:{type:"string",description:"Repository identifier (owner/repo)"}},required:["repository"]}},{name:"list_repositories",description:"List all available repositories that have been connected and indexed",inputSchema:{type:"object",properties:{}}},{name:"start_indexing",description:"Start indexing a repository",inputSchema:{type:"object",properties:{owner:{type:"string",description:"Repository owner"},repo:{type:"string",description:"Repository name"},incremental:{type:"boolean",description:"Perform incremental indexing"},branch:{type:"string",description:"Branch to index"}},required:["owner","repo"]}},{name:"get_indexing_status",description:"Get the status of a repository indexing task",inputSchema:{type:"object",properties:{taskId:{type:"string",description:"Indexing task ID"}},required:["taskId"]}}]}async handleToolCall(e,t){switch(e){case"store_memory":return{content:[{type:"text",text:`Memory stored successfully with ID: ${(await this.apiClient.storeMemory({repository:t.repository,content:t.content,context:t.context,metadata:t.metadata})).memoryId}`}]};case"search_memories":let i=await this.apiClient.searchMemories({repository:t.repository,query:t.query,limit:t.limit,threshold:t.threshold});return{content:[{type:"text",text:JSON.stringify(i,null,2)}]};case"search_code":let s=await this.apiClient.searchCode({repository:t.repository,query:t.query,language:t.language,path:t.path,limit:t.limit});return{content:[{type:"text",text:JSON.stringify(s,null,2)}]};case"get_file_context":let o=await this.apiClient.getFileContext({repository:t.repository,filePath:t.filePath,lineStart:t.lineStart,lineEnd:t.lineEnd});return{content:[{type:"text",text:JSON.stringify(o,null,2)}]};case"get_project_overview":let a=await this.apiClient.getProjectOverview({repository:t.repository});return{content:[{type:"text",text:JSON.stringify(a,null,2)}]};case"list_repositories":let u=await this.apiClient.listRepositories();return{content:[{type:"text",text:JSON.stringify(u,null,2)}]};case"start_indexing":let p=await this.apiClient.startIndexing({owner:t.owner,repo:t.repo,incremental:t.incremental,branch:t.branch});return{content:[{type:"text",text:`Indexing started. Task ID: ${p.taskId}, Status: ${p.status}`}]};case"get_indexing_status":let v=await this.apiClient.getIndexingTask({taskId:t.taskId});return{content:[{type:"text",text:JSON.stringify(v,null,2)}]};default:throw new Error(`Unknown tool: ${e}`)}}generateRequestId(){return Q()}createRequestContext(e,t,r){let i={requestId:e,timestamp:new Date,method:t,params:r,startTime:Date.now()};return this.activeRequests.set(e,i),i}setState(e){let t=this.state;this.state=e,this.logger.info("State change",{from:t,to:e})}async start(){try{if(this.setState("starting"),this.logger.info("Starting Timofi MCP Client",{name:this.config.name,version:this.config.version,apiUrl:this.config.apiUrl}),!await this.apiClient.healthCheck())throw new Error("API server is not accessible");this.transport=new E,await this.server.connect(this.transport),this.setState("ready"),this.logger.info("Timofi MCP Client started successfully"),this.emit("started",{config:this.config}),this.emit("ready",{uptime:this.getUptime()})}catch(e){throw this.setState("error"),this.logger.error("Failed to start MCP Client",e),this.emit("error",{error:e}),e}}async shutdown(e="manual"){if(this.state==="shutting_down"||this.state==="stopped")return;this.setState("shutting_down"),this.logger.info(`Shutting down client (reason: ${e})`);let t=new Promise(r=>{this.shutdownTimer=setTimeout(()=>{this.logger.warn("Forced shutdown after timeout"),r()},this.config.shutdownTimeout)});try{await Promise.race([this.waitForActiveRequests(),t]),await this.apiClient.processOfflineQueue(),this.server&&this.transport&&await this.server.close(),this.cleanupProcessHandlers(),this.setState("stopped"),this.logger.info("Client shutdown completed"),this.emit("shutdown",{reason:e})}catch(r){this.logger.error("Error during shutdown",r),this.setState("error"),this.emit("error",{error:r})}finally{this.shutdownTimer&&clearTimeout(this.shutdownTimer)}}async waitForActiveRequests(){let r=0;for(;this.activeRequests.size>0&&r<3e3;)await new Promise(i=>setTimeout(i,100)),r+=100;this.activeRequests.size>0&&this.logger.warn(`${this.activeRequests.size} requests still active during shutdown`)}getState(){return this.state}getUptime(){return Date.now()-this.startTime.getTime()}getConfig(){return{...this.config}}getActiveRequestsCount(){return this.activeRequests.size}getCacheStats(){return this.apiClient.getCacheStats()}getQueueStatus(){return this.apiClient.getQueueStatus()}invalidateCache(e){return this.apiClient.invalidateCache(e)}};import*as T from"dotenv";T.config();var h=new c("MCPClientCLI"),z=["TIMOFI_API_URL","TIMOFI_API_KEY"],w=z.filter(n=>!process.env[n]);w.length>0&&(h.error("Missing required environment variables",void 0,{missing:w}),console.error(`
+Missing required environment variables: ${w.join(", ")}
+`),console.error("Please configure your .env file with:"),console.error("  TIMOFI_API_URL=http://localhost:3000"),console.error(`  TIMOFI_API_KEY=your-api-key
+`),process.exit(1));async function $(){try{let n={name:"timofi-context-server",version:process.env.npm_package_version||"1.0.0",apiUrl:process.env.TIMOFI_API_URL,apiKey:process.env.TIMOFI_API_KEY,environment:process.env.NODE_ENV||"development",cacheEnabled:process.env.CACHE_ENABLED!=="false",cacheTTL:parseInt(process.env.CACHE_TTL||"300000"),offlineQueueEnabled:process.env.OFFLINE_QUEUE_ENABLED!=="false"};h.info("Initializing Timofi MCP Client",{name:n.name,version:n.version,apiUrl:n.apiUrl,cacheEnabled:n.cacheEnabled,offlineQueueEnabled:n.offlineQueueEnabled});let e=new y(n);e.on("started",()=>{h.info("MCP Client started successfully")}),e.on("ready",({uptime:t})=>{h.info("MCP Client ready",{uptime:t})}),e.on("error",({error:t})=>{h.error("MCP Client error",t)}),e.on("shutdown",({reason:t})=>{h.info("MCP Client shutdown",{reason:t})}),await e.start(),h.info("Timofi MCP Client is running")}catch(n){h.error("Failed to start MCP Client",n),process.exit(1)}}$().catch(n=>{h.error("Unhandled error in main",n),process.exit(1)});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@timofi/context-server",
+  "version": "1.0.0",
+  "description": "MCP client for Timofi Context Server - Repository-aware memory and code intelligence for Claude Desktop",
+  "type": "module",
+  "bin": {
+    "timofi-mcp-client": "dist/mcp-client-cli.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.4.0",
+    "axios": "^1.6.2",
+    "dotenv": "^16.3.1",
+    "uuid": "^9.0.1",
+    "winston": "^3.11.0"
+  },
+  "license": "MIT",
+  "author": "GoldCode.io <team@goldcode.io>",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "code-intelligence",
+    "github",
+    "repository",
+    "ai-assistant",
+    "claude-code",
+    "sourcegraph",
+    "vector-database"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/goldcode-io/timofi-context-server.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}