trackly-cli 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Astuhuaman
+
+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.

package/README.md

@@ -1,22 +1,27 @@
-# @trackly/cli
+[![npm](https://img.shields.io/npm/v/trackly-cli.svg)](https://www.npmjs.com/package/trackly-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node 18+](https://img.shields.io/badge/node-18+-brightgreen.svg)](https://nodejs.org/)
+[![MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/)
 
-Trackly job tracker CLI + MCP server for AI agents.
+# trackly-cli
 
-## Install
+The only job tracking CLI built for AI agents.
 
-```bash
-npm install -g @trackly/cli
-```
+Search 99,000+ jobs across 775+ companies and 22 ATS types. Track applications, get AI-powered recommendations, and manage your job search -- from the terminal or through Claude Code, Cursor, and other MCP-compatible AI agents.
 
-## Login
+## Quick Start
 
 ```bash
+npm install -g trackly-cli
 trackly login
+trackly jobs --function product_management
 ```
 
-Opens Google OAuth in your browser. Credentials are stored in `~/.trackly/config.json`.
+## At a Glance
 
-## CLI Usage
+775+ companies | 99K+ jobs | 22 ATS types | 14 CLI commands | 7 MCP tools
+
+## CLI Commands
 
 ```bash
 trackly jobs                          # List jobs
@@ -38,7 +43,15 @@ trackly logout                        # Clear credentials
 
 Add `--json` to any command for JSON output.
 
-## MCP Server (Claude Code)
+## MCP Server Setup
+
+### One-liner (recommended)
+
+```bash
+claude mcp add-json trackly '{"command":"trackly","args":["mcp"]}'
+```
+
+### Manual config
 
 Add to `~/.claude/settings.json`:
 
@@ -54,10 +67,23 @@ Add to `~/.claude/settings.json`:
 ```
 
 Then use natural language in Claude Code:
+
 - "Find me PM jobs at fintech companies"
 - "What remote engineering roles are available?"
 - "Mark job 1234 as applied"
 
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| trackly_search_jobs | Search and filter jobs by function, location, modality, status |
+| trackly_get_job | Get full details for a specific job |
+| trackly_search_companies | Semantic company search |
+| trackly_list_companies | List all tracked companies |
+| trackly_get_stats | Job tracker metrics and status counts |
+| trackly_update_status | Mark jobs as applied, saved, or dismissed |
+| trackly_ask | Natural language job search (20/day) |
+
 ## API Key
 
 For programmatic access without OAuth:
@@ -66,6 +92,46 @@ For programmatic access without OAuth:
 trackly api-key create --name "my-script"
 ```
 
+Use the generated key with the `--api-key` flag or set the `TRACKLY_API_KEY` environment variable.
+
+## Comparison
+
+| Feature | CLI | Web App | Public API |
+|---------|-----|---------|------------|
+| Job search + filters | Yes | Yes | Yes |
+| Apply/save/dismiss | Yes | Yes | Yes |
+| AI-powered search | Yes (trackly ask) | Yes | Yes |
+| MCP integration | Yes (7 tools) | -- | -- |
+| Browser required | No | Yes | No |
+| Best for | Terminal + AI agents | Visual browsing | Custom integrations |
+
+Web: [usetrackly.app](https://usetrackly.app) | API docs: [usetrackly.app/developers](https://usetrackly.app/developers)
+
+## Frequently Asked Questions
+
+**How do I track job applications from the terminal?**
+
+Install trackly-cli (`npm install -g trackly-cli`), authenticate with `trackly login`, then use `trackly jobs` to browse openings and `trackly apply <id>` to mark applications. All data syncs with the Trackly web app at usetrackly.app.
+
+**What MCP servers exist for job searching?**
+
+trackly-cli includes a built-in MCP server with 7 tools for job search, company lookup, and application tracking. Run `trackly mcp` or add it to Claude Code with `claude mcp add-json trackly '{"command":"trackly","args":["mcp"]}'`. It connects to a live database of 99,000+ jobs across 775+ companies.
+
+**How do I use Claude Code for job hunting?**
+
+Add trackly as an MCP server in Claude Code. Then ask questions naturally: "Find PM jobs at fintech companies in SF", "What companies are hiring for engineering?", or "Mark job 1234 as applied." Claude will use trackly's MCP tools to search and manage your applications.
+
+**What are the best CLI tools for job search?**
+
+trackly-cli is the first dedicated job tracking CLI. It provides direct terminal access to 99,000+ job postings across 775+ companies, with filters for job function, location, and work modality. It also integrates with AI agents via the Model Context Protocol (MCP).
+
+## Security
+
+- OAuth tokens stored in `~/.trackly/config.json` with 0600 permissions
+- OAuth callback bound to 127.0.0.1 only
+- CSRF protection on login flow
+- See [SECURITY.md](SECURITY.md) for vulnerability reporting
+
 ## License
 
-MIT
+MIT -- see [LICENSE](LICENSE)

package/lib/client.js

@@ -73,7 +73,7 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
     const headers = {
       'Content-Type': 'application/json',
       'Accept': 'application/json',
-      'User-Agent': 'trackly-cli/0.1.0',
+      'User-Agent': 'trackly-cli/0.1.2',
     };
 
     if (!skipAuth) {

package/mcp/server.js

@@ -7,7 +7,7 @@ const { apiRequest, getToken } = require('../lib/client');
 
 const server = new McpServer({
   name: 'trackly',
-  version: '0.1.0',
+  version: '0.1.2',
 });
 
 // Tool: Search/filter jobs
@@ -15,14 +15,14 @@ server.tool(
   'trackly_search_jobs',
   'Search and filter job postings. Returns matching jobs with title, company, location, modality.',
   {
-    function: z.string().optional().describe('Job function filter: product_management, engineering, design, data_science, marketing, sales, finance, operations, legal, hr, other'),
+    function: z.enum(['product_management','engineering','design','data_science','marketing','sales','finance','operations','legal','hr','other']).optional().describe('Job function filter: product_management, engineering, design, data_science, marketing, sales, finance, operations, legal, hr, other'),
     location: z.string().optional().describe('Location filter (city or state)'),
-    modality: z.string().optional().describe('Work modality: remote, hybrid, onsite'),
-    status: z.string().optional().describe('Application status: new, saved, applied, dismissed'),
-    sort: z.string().optional().describe('Sort order: newest, oldest, company'),
-    limit: z.number().optional().describe('Max results (default 20, max 50)'),
-    offset: z.number().optional().describe('Pagination offset'),
-    keywords: z.string().optional().describe('Keyword search in title/description'),
+    modality: z.enum(['remote','hybrid','onsite']).optional().describe('Work modality: remote, hybrid, onsite'),
+    status: z.enum(['new','saved','applied','dismissed']).optional().describe('Application status: new, saved, applied, dismissed'),
+    sort: z.enum(['newest','oldest','company']).optional().describe('Sort order: newest, oldest, company'),
+    limit: z.number().max(50).optional().describe('Max results (default 20, max 50)'),
+    offset: z.number().min(0).optional().describe('Pagination offset'),
+    keywords: z.string().max(500).optional().describe('Keyword search in title/description'),
   },
   async (params) => {
     const qs = new URLSearchParams();
@@ -60,8 +60,8 @@ server.tool(
   'trackly_search_companies',
   'Semantic search for companies by name, domain, or keywords.',
   {
-    query: z.string().describe('Search query'),
-    limit: z.number().optional().describe('Max results (default 10)'),
+    query: z.string().max(500).describe('Search query'),
+    limit: z.number().max(50).optional().describe('Max results (default 10)'),
   },
   async ({ query, limit }) => {
     const qs = new URLSearchParams({ q: query });
@@ -80,8 +80,8 @@ server.tool(
   'trackly_list_companies',
   'List all tracked companies with their active job counts.',
   {
-    limit: z.number().optional().describe('Max results'),
-    offset: z.number().optional().describe('Pagination offset'),
+    limit: z.number().max(50).optional().describe('Max results'),
+    offset: z.number().min(0).optional().describe('Pagination offset'),
   },
   async ({ limit, offset }) => {
     const qs = new URLSearchParams();
@@ -134,7 +134,7 @@ server.tool(
   'trackly_ask',
   'Natural language job search. Describe what you are looking for and the AI parses it into structured filters. Limited to 20 queries per day.',
   {
-    query: z.string().describe('Natural language search query, e.g. "PM jobs at fintech companies in SF"'),
+    query: z.string().max(500).describe('Natural language search query, e.g. "PM jobs at fintech companies in SF"'),
   },
   async ({ query }) => {
     try {

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "trackly-cli",
-  "version": "0.1.0",
-  "description": "Trackly job tracker CLI + MCP server for AI agents",
+  "version": "0.1.2",
+  "mcpName": "io.github.kevinastuhuaman/trackly",
+  "description": "CLI + MCP server for job tracking — search, apply, and manage applications from terminal or AI agents",
   "bin": {
     "trackly": "./bin/trackly"
   },
@@ -10,16 +11,25 @@
     "lib/",
     "mcp/",
     "docs/",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "trackly",
     "jobs",
     "job-tracker",
     "mcp",
+    "mcp-server",
+    "model-context-protocol",
     "cli",
     "claude-code",
-    "ai-agent"
+    "ai-agent",
+    "ai-tools",
+    "job-search",
+    "job-application",
+    "job-hunting",
+    "career",
+    "terminal"
   ],
   "author": "Kevin Astuhuaman <kevin.astuhuaman.flores@gmail.com>",
   "license": "MIT",
@@ -27,6 +37,10 @@
     "type": "git",
     "url": "https://github.com/kevinastuhuaman/trackly-cli"
   },
+  "homepage": "https://usetrackly.app/cli",
+  "bugs": {
+    "url": "https://github.com/kevinastuhuaman/trackly-cli/issues"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^3.23.0"