applydjinn-mcp 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ApplyDjinn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,295 @@
1
- # Temporary Holding Version
1
+ # ApplyDjinn MCP — jobs, company research, engineering lessons and your profile
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The official **ApplyDjinn Model Context Protocol server** connects an AI assistant to [ApplyDjinn](https://applydjinn.com): tech vacancies, hiring companies, attributed company news, engineering courses, interview preparation and your own candidate profile.
4
+
5
+ Search with tools and receive structured information plus **direct ApplyDjinn page links**. Connect your account in the browser when you want the agent to read or edit your information. The server runs locally over stdio, uses the official MCP SDK, and works with modern and 2025-era MCP clients.
6
+
7
+ [Setup and full documentation](https://applydjinn.com/mcp-server) · [Explore the website](https://applydjinn.com) · [Engineering courses](https://applydjinn.com/typorithm) · [iPhone app and screenshots](https://applydjinn.com/iphone) · [Support](https://applydjinn.com/contact)
8
+
9
+ ## What you can do
10
+
11
+ - Find active technology vacancies by keywords, skills, locations, category and work format.
12
+ - Get a role summary with its canonical ApplyDjinn URL, company context and source dates.
13
+ - Research company hiring activity and compare technology demand.
14
+ - Read attributed company news summaries with direct article and company links.
15
+ - Explore engineering courses, search lessons and retrieve worked code examples and prepared results.
16
+ - Practise original self-check and interview questions; request answers when you want to review them.
17
+ - Find career guides, company interview preparation and worked engineering exercises.
18
+ - Connect your account to read your profile, CV text, experience, skills, education and portfolio.
19
+ - Fill or edit your name, phone, job preferences, profile text and profile records with explicit editing permission.
20
+ - Optionally read saved application documents with a separate permission.
21
+ - Revoke a connection on the website or disconnect from the MCP client.
22
+
23
+ This package does not call an AI model itself. Your chosen MCP host decides which model to use and which tools to call.
24
+
25
+ ## Quick start
26
+
27
+ Requires **Node.js 20 or later**. No ApplyDjinn password belongs in a configuration file or an AI conversation.
28
+
29
+ ```sh
30
+ npx -y applydjinn-mcp@1.0.0
31
+ ```
32
+
33
+ This starts an MCP server waiting on stdin/stdout. It is intended to be launched by an MCP host.
34
+
35
+ Add this stdio server to your MCP client's configuration:
36
+
37
+ ```json
38
+ {
39
+ "mcpServers": {
40
+ "applydjinn": {
41
+ "command": "npx",
42
+ "args": ["-y", "applydjinn-mcp@1.0.0"]
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ The exact configuration location depends on your MCP host. The command and arguments are the same in clients that support locally launched stdio servers. Pinning the version makes installation reproducible.
49
+
50
+ ### Sign in through the browser
51
+
52
+ ```sh
53
+ npx -y applydjinn-mcp@1.0.0 login
54
+ ```
55
+
56
+ 1. The command opens ApplyDjinn in your browser.
57
+ 2. Sign in with your existing account, including your normal passkey flow if you use one.
58
+ 3. Review the requested permissions and explicitly approve the connection.
59
+ 4. The browser returns a one-time code to a loopback listener on your computer.
60
+ 5. The CLI saves a private local session. Return to your AI client and ask it to use ApplyDjinn.
61
+
62
+ You can also ask your MCP host to call `connect_account`. It returns the same browser approval URL. After approving, call `connection_status` to see whether the connection is ready.
63
+
64
+ Use a read-only connection when you only want research and profile reading:
65
+
66
+ ```sh
67
+ npx -y applydjinn-mcp@1.0.0 login --read-only
68
+ ```
69
+
70
+ Document access is optional:
71
+
72
+ ```sh
73
+ npx -y applydjinn-mcp@1.0.0 login --documents
74
+ ```
75
+
76
+ These options can be combined. Each connection is shown in [Account → Connected AI agents](https://applydjinn.com/account/agents).
77
+
78
+ ### Public research with an API key
79
+
80
+ Original learning content, guide lookup and destination links are available without an account. Hiring research and news require either a browser-approved connection with public-research permission or a personal read-only data key.
81
+
82
+ Create a key in [Account → Data API keys](https://applydjinn.com/account/api). Configure `APPLYDJIN_DATA_API_KEY` through your MCP host's secret/environment settings. A data key grants public research only; it cannot read or edit a candidate profile or a saved document.
83
+
84
+ ```json
85
+ {
86
+ "mcpServers": {
87
+ "applydjinn": {
88
+ "command": "npx",
89
+ "args": ["-y", "applydjinn-mcp@1.0.0"],
90
+ "env": {
91
+ "APPLYDJIN_DATA_API_KEY": "YOUR_PERSONAL_READ_ONLY_DATA_KEY"
92
+ }
93
+ }
94
+ }
95
+ }
96
+ ```
97
+
98
+ Do not paste a real key into a shared configuration, issue, prompt or repository. Prefer the browser login if you want account tools.
99
+
100
+ ## Tools
101
+
102
+ The package exposes **27 tools**: 24 site-backed tools and three local connection tools. Tool schemas describe accepted fields and annotate read-only, editing and destructive actions for the host.
103
+
104
+ ### Jobs, companies, news and market evidence
105
+
106
+ | Tool | Use |
107
+ | --- | --- |
108
+ | `find_links` | Get direct website destinations for jobs, companies, news, learning and guides. |
109
+ | `search_vacancies` | Filter current roles by search, skills, locations, category and work format. |
110
+ | `get_vacancy` | Read one current role summary with its canonical page URL. |
111
+ | `company_hiring_activity` | Find employers, active role counts and leading technologies. |
112
+ | `technology_demand` | Inspect demand for one technology and its evidence scope. |
113
+ | `compare_technologies` | Compare two to ten technologies in the same location scope. |
114
+ | `market_snapshot` | Read catalog coverage, observation windows and quality indicators. |
115
+ | `search_news` | Get attributed summaries, source dates and ApplyDjinn article/company URLs. |
116
+
117
+ Hiring records retain the public API's publication scope. Full scraped job descriptions and original application URLs are not republished by these tools. Open the ApplyDjinn vacancy page for its application controls and attribution. News tools return summaries rather than publisher article bodies.
118
+
119
+ ### Lessons, interview practice and guides
120
+
121
+ | Tool | Use |
122
+ | --- | --- |
123
+ | `list_courses` | Explore course descriptions, categories, cover previews and lesson counts. |
124
+ | `search_lessons` | Search lesson titles and tags, with exact course and lesson links. |
125
+ | `get_course` | Read the complete outline of one course without loading lesson bodies. |
126
+ | `get_lesson` | Read one lesson, worked code examples, prepared results and practice questions. |
127
+ | `interview_questions` | Get original questions from a course, with optional answers. |
128
+ | `search_guides` | Find career and company interview preparation guides. |
129
+ | `get_guide` | Read one original guide, exercises, worked examples and source references. |
130
+
131
+ Courses include algorithms, JavaScript, TypeScript, Python, SQL, backend engineering, system design, security, AI, NumPy, pandas, SQLAlchemy and ETL/Data Engineering. Use `list_courses` for the current catalog rather than relying on a fixed count.
132
+
133
+ `get_lesson` and `interview_questions` omit correct-answer flags and explanations by default. Set `includeAnswers: true` when reviewing. Reading a lesson does not execute its code. Course content is requested only by content tools; listing courses does not download every course.
134
+
135
+ ### Your account and profile
136
+
137
+ | Tool | Permission | Use |
138
+ | --- | --- | --- |
139
+ | `get_account` | Account reading | Account email, workspace and credit balance. |
140
+ | `get_profile` | Profile reading | Profile, identity version, skills, experience, education, languages, portfolio and showcase. |
141
+ | `update_profile` | Profile editing | Update supplied job-preference and profile-text fields. |
142
+ | `update_profile_identity` | Profile editing | Edit name and phone using the current identity version. |
143
+ | `save_profile_item` | Profile editing | Add or edit a skill, experience, education, language, certificate, portfolio link or agentic-tool experience. |
144
+ | `delete_profile_item` | Profile editing | Delete one owned record after an explicit request and `confirm: true`. |
145
+ | `update_profile_showcase` | Profile editing | Edit headline, introduction, selected courses and CV links. |
146
+ | `list_documents` | Document reading | List your own saved application documents and workspace links. |
147
+ | `get_document` | Document reading | Read one of your own saved documents. |
148
+
149
+ Account credentials, payment actions and public visibility controls remain on the website. Profile editing does not turn on recruiter discovery or publish a profile. Editing a name or phone retains an existing profile address and does not spend credits; the first free address remains unpublished.
150
+
151
+ ### Connection tools
152
+
153
+ | Tool | Use |
154
+ | --- | --- |
155
+ | `connect_account` | Start browser approval; accepts read-only and document-access options. |
156
+ | `connection_status` | Show granted permissions and expiry without returning secrets. |
157
+ | `disconnect_account` | Revoke this connection and remove local sign-in; requires `confirm: true`. |
158
+
159
+ If a network failure prevents confirmed revocation, the result says so and provides the website's connection-management link.
160
+
161
+ ## Example requests for your AI assistant
162
+
163
+ - “Find remote Python backend roles in Germany. Give me ApplyDjinn vacancy and company links and explain the core requirements.”
164
+ - “Compare PostgreSQL and MongoDB demand in the same country, keeping the observation dates and coverage limits.”
165
+ - “Show recent attributed company updates for this employer and link each original ApplyDjinn news page.”
166
+ - “Find the ETL course and explain the immutable raw-input lesson with its worked code.”
167
+ - “Ask me five original interview practice questions. Wait for my attempt before showing the answers.”
168
+ - “Connect my account read-only and summarise my existing skills and experience.”
169
+ - “After I approve editing, add my new Python experience and update the education record I selected.”
170
+
171
+ The package also provides `job_search` and `interview_practice` prompt templates and an `applydjinn://documentation` resource.
172
+
173
+ ## Profile editing examples
174
+
175
+ Read `get_profile` before editing. Existing record IDs belong to that connected account; supplying another user's ID cannot grant access.
176
+
177
+ Add a skill:
178
+
179
+ ```json
180
+ {
181
+ "kind": "skill",
182
+ "data": {
183
+ "skillName": "Python",
184
+ "experienceYears": 3,
185
+ "proficiencyLevel": "advanced"
186
+ }
187
+ }
188
+ ```
189
+
190
+ Edit an existing experience with `save_profile_item`:
191
+
192
+ ```json
193
+ {
194
+ "kind": "experience",
195
+ "id": "EXISTING_RECORD_ID_FROM_GET_PROFILE",
196
+ "data": {
197
+ "description": "The revised description supplied and approved by the user."
198
+ }
199
+ }
200
+ ```
201
+
202
+ Supported item fields:
203
+
204
+ | Kind | Fields |
205
+ | --- | --- |
206
+ | `skill` | `skillName`, `experienceYears`, `proficiencyLevel` |
207
+ | `experience` | `company`, `role`, `startDate`, `endDate`, `description`, `domain` |
208
+ | `education` | `institution`, `degree`, `field`, `startDate`, `endDate` |
209
+ | `language` | `language`, `proficiencyLevel` |
210
+ | `certification` | `name`, `issuer`, `dateObtained`, `expiryDate` |
211
+ | `portfolio` | `type`, `url`, `title` |
212
+ | `agentic_tool` | Existing catalog `name` or `skillId`, plus `experienceMonths` |
213
+
214
+ Names and phone numbers use `update_profile_identity` with `expectedVersion` from `get_profile.identity.version`. This prevents a stale request from overwriting a newer identity edit.
215
+
216
+ Dates use `YYYY-MM-DD`. Use the schemas returned by `tools/list` for supported enums and limits. Empty or invalid updates are rejected. The server does not infer years of experience or invent employers, certificates or degrees.
217
+
218
+ ## Session handling and permissions
219
+
220
+ - Browser approval uses a one-time authorization code, S256 PKCE, state verification and an exact local callback.
221
+ - The password is entered only on ApplyDjinn. It is never a tool argument.
222
+ - Access tokens are short-lived and issued specifically for the agent API. They are not ordinary website/native-app session tokens.
223
+ - Refresh tokens rotate on use. Their server-side values are stored as hashes.
224
+ - The overall connection expires after 30 days. Revocation blocks both token types immediately.
225
+ - Account suspension, deletion or a changed account security version invalidates the connection.
226
+ - The CLI stores sign-in in the current user's private configuration directory and uses mode `0600` for the session file on POSIX systems.
227
+ - The MCP server writes protocol messages to stdout; operational messages use stderr.
228
+ - Tool responses contain relevant data and links, without promotional footers or credentials.
229
+
230
+ Your selected AI host/provider may receive information returned by the tools. Only approve the permissions you want that client to use. See [Privacy](https://applydjinn.com/privacy) and [Connected AI agents](https://applydjinn.com/account/agents).
231
+
232
+ ## Configuration and commands
233
+
234
+ | Setting | Purpose |
235
+ | --- | --- |
236
+ | `APPLYDJIN_DATA_API_KEY` | Optional read-only key for public research. |
237
+ | `APPLYDJIN_CONFIG_DIR` | Optional absolute path to a private local session directory. |
238
+ | `APPLYDJIN_AGENT_ACCESS_TOKEN` | Optional externally managed short-lived agent token. Browser login is recommended for normal use. |
239
+
240
+ ```sh
241
+ npx -y applydjinn-mcp@1.0.0 --help
242
+ npx -y applydjinn-mcp@1.0.0 --version
243
+ npx -y applydjinn-mcp@1.0.0 status
244
+ npx -y applydjinn-mcp@1.0.0 logout
245
+ ```
246
+
247
+ `login --no-open` prints the approval URL when the CLI cannot launch a browser. The browser must run on the same computer as the CLI so it can return to the loopback listener. For an SSH or headless host, forward the exact loopback callback securely or sign in locally and use an explicitly managed session; never expose the callback listener to the public network.
248
+
249
+ There is no need to configure a third-party model API key in this server. Using an AI host may have its own costs. Optional ApplyDjinn credit purchases remain separate from this package.
250
+
251
+ ## ApplyDjinn on the web and iPhone
252
+
253
+ Use [ApplyDjinn on the web](https://applydjinn.com) to inspect complete vacancy pages, company profiles, market research, document tools and engineering courses.
254
+
255
+ [![ApplyDjinn website showing hiring research and application tools](https://applydjinn.com/mcp-media/website.webp)](https://applydjinn.com)
256
+
257
+ The native iPhone app is **available on the App Store**. It connects to the same ApplyDjinn account. See the [app page](https://applydjinn.com/iphone) for compatibility, real screenshots and the status of upcoming offline-learning features.
258
+
259
+ [![Download on the App Store](https://applydjinn.com/iphone/app-store-badge.svg)](https://apps.apple.com/app/id6820561847)
260
+
261
+ | Hiring research on iPhone | Engineering lessons on iPhone |
262
+ | --- | --- |
263
+ | [![ApplyDjinn iPhone market screen](https://applydjinn.com/iphone/market.webp)](https://applydjinn.com/iphone) | [![ApplyDjinn iPhone learning screen](https://applydjinn.com/iphone/learning.webp)](https://applydjinn.com/iphone) |
264
+
265
+ These are actual published App Store screenshots. App Store is a service mark of Apple Inc.
266
+
267
+ ## Data interpretation and limits
268
+
269
+ ApplyDjinn describes its observed technology-hiring catalog, rather than every job in the market. Preserve timestamps, source attribution, denominators and missing-data labels. An archived or expired listing is not a promise that applications remain open.
270
+
271
+ Use canonical ApplyDjinn links in your answer. Public research follows the [data license](https://applydjinn.com/data-license), [methodology](https://applydjinn.com/methodology) and [content policy](https://applydjinn.com/content-policy). Installing an npm package does not grant additional rights to third-party source material.
272
+
273
+ The agent API limits requests, validates schemas and bounds response sizes. Respect a `429` response and `Retry-After`. Profile writes have a tighter budget. Do not automatically retry a timed-out creation: first read the profile to check whether the record was saved.
274
+
275
+ The existing remote read-only MCP endpoint at `https://applydjinn.com/mcp` remains available for public-data clients using a personal data key. This npm server adds lesson/guide tools and local browser-authorized account tools. Private account access is optional and separate from public research.
276
+
277
+ ## Troubleshooting
278
+
279
+ | Symptom | Action |
280
+ | --- | --- |
281
+ | Server appears to wait in a terminal | It is waiting for an MCP host on stdio. Add the configuration shown above. |
282
+ | `401` for research | Sign in or configure a valid personal data key. |
283
+ | `401` for account tools | Connect again; the session may have expired, been revoked or been invalidated by an account change. |
284
+ | `403` for an edit | The connection is read-only or lacks the required permission. Reconnect and approve editing. |
285
+ | A profile item is unavailable | Read `get_profile` for your current IDs and verify the requested record belongs to your account. |
286
+ | Identity version conflict | Read the latest profile and retry only the fields the user wants changed. |
287
+ | Connection cannot return from the browser | Use a browser on the same computer as the CLI and allow its local loopback connection. |
288
+ | Session file permission error | Use a private current-user directory and reconnect; do not share the session file. |
289
+ | Result too large | Request one lesson or fewer result items. |
290
+
291
+ ## License and support
292
+
293
+ The MCP client software is MIT licensed. Website content, data, employer identities and Apple assets retain their own applicable rights; they are not relicensed by the package's software license.
294
+
295
+ [Full MCP documentation](https://applydjinn.com/mcp-server) · [Public data API](https://applydjinn.com/data) · [Support and corrections](https://applydjinn.com/contact)
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/env node
2
+ import { readFileSync } from 'node:fs';
3
+ import { serveStdio } from '@modelcontextprotocol/server/stdio';
4
+ import { createApplyDjinnServer } from '../lib/server.mjs';
5
+ import { beginLogin, cancelLogin } from '../lib/login.mjs';
6
+ import { connectionStatus, disconnectAccount } from '../lib/api.mjs';
7
+
8
+ const args = process.argv.slice(2); const command = args[0] || 'serve';
9
+ const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
10
+ try {
11
+ if (command === '--version' || command === '-v') console.log(version);
12
+ else if (command === '--help' || command === '-h' || command === 'help') console.log(`ApplyDjinn MCP ${version}\n\nUsage:\n applydjinn-mcp Start the MCP stdio server\n applydjinn-mcp login Sign in through the browser and approve access\n applydjinn-mcp login --read-only\n applydjinn-mcp login --documents\n applydjinn-mcp status Show connection status without credentials\n applydjinn-mcp logout Revoke access and remove local sign-in\n\nGuide: https://applydjinn.com/mcp-server\nPublic data key (optional): APPLYDJIN_DATA_API_KEY\n`);
13
+ else if (command === 'login') {
14
+ const started = await beginLogin({ readOnly: args.includes('--read-only'), documents: args.includes('--documents'), open: !args.includes('--no-open') });
15
+ console.log(`Open this page and review the permissions:\n${started.url}\nWaiting for your approval…`);
16
+ console.log(JSON.stringify(await started.promise, null, 2));
17
+ } else if (command === 'status') console.log(JSON.stringify(await connectionStatus(), null, 2));
18
+ else if (command === 'logout') console.log(JSON.stringify(await disconnectAccount(), null, 2));
19
+ else if (command === 'serve') {
20
+ const handle = serveStdio(createApplyDjinnServer, { onerror: () => console.error('ApplyDjinn MCP transport error') });
21
+ process.stdin.on('end', cancelLogin);
22
+ for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => { cancelLogin(); void handle.close().finally(() => process.exit(0)); });
23
+ } else { console.error('Unknown command. Use applydjinn-mcp --help.'); process.exitCode = 1; }
24
+ } catch (error) { console.error(error instanceof Error ? error.message : 'ApplyDjinn MCP could not start.'); process.exitCode = 1; }
package/lib/api.mjs ADDED
@@ -0,0 +1,62 @@
1
+ import { readCredentials, saveCredentials, withCredentialLock, clearCredentials } from './credentials.mjs';
2
+
3
+ export const ISSUER = 'https://applydjinn.com';
4
+ export const RESOURCE = ISSUER + '/api/agents';
5
+ export const CLIENT_ID = 'applydjinn-mcp-cli';
6
+ export function apiOrigin() {
7
+ const value = process.env.APPLYDJIN_BASE_URL || ISSUER;
8
+ const url = new URL(value);
9
+ const local = process.env.APPLYDJIN_ALLOW_LOCAL_TESTING === '1' && url.protocol === 'http:' && url.hostname === '127.0.0.1' && !!url.port;
10
+ if ((!local && url.origin !== ISSUER) || url.pathname !== '/' || url.username || url.password || url.search || url.hash) throw new Error('Use the official ApplyDjinn origin. Local test origins require explicit test configuration.');
11
+ return url.origin;
12
+ }
13
+ export class AgentApiError extends Error {
14
+ constructor(status, message, details = {}) { super(message); this.status = status; this.details = details; }
15
+ }
16
+ export async function requestJson(path, { token, body, method = 'POST', fetcher = fetch } = {}) {
17
+ if (!/^\/api\/agents\/(?:tools|token|logout)$/.test(path)) throw new Error('Unsupported ApplyDjinn endpoint');
18
+ let response;
19
+ try { response = await fetcher(apiOrigin() + path, { method, redirect: 'error', signal: AbortSignal.timeout(25_000),
20
+ headers: { Accept: 'application/json', ...(body === undefined ? {} : { 'Content-Type': 'application/json' }), ...(token ? { Authorization: `Bearer ${token}` } : {}) },
21
+ ...(body === undefined ? {} : { body: JSON.stringify(body) }) }); }
22
+ catch { throw new AgentApiError(0, 'The ApplyDjinn request did not complete. For an edit, inspect your profile before retrying to avoid duplicate items.'); }
23
+ if (!response.body) throw new AgentApiError(response.status, 'ApplyDjinn returned an empty response.');
24
+ const reader = response.body.getReader(); let bytes = 0; const chunks = [];
25
+ try {
26
+ for (;;) { const part = await reader.read(); if (part.done) break; bytes += part.value.byteLength;
27
+ if (bytes > 600 * 1024) { await reader.cancel(); throw new AgentApiError(413, 'The result was too large. Request fewer items.'); } chunks.push(part.value); }
28
+ } finally { reader.releaseLock(); }
29
+ let value; try { value = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw new AgentApiError(response.status, 'ApplyDjinn returned an unexpected response.'); }
30
+ if (!response.ok) throw new AgentApiError(response.status, String(value.error_description || value.error || 'ApplyDjinn request failed').slice(0, 300), { requiredScope: value.requiredScope, issues: value.issues, retryAfter: response.headers.get('retry-after') });
31
+ return value;
32
+ }
33
+ export async function accessToken() {
34
+ if (process.env.APPLYDJIN_AGENT_ACCESS_TOKEN) return process.env.APPLYDJIN_AGENT_ACCESS_TOKEN;
35
+ const stored = await readCredentials();
36
+ if (!stored) throw new AgentApiError(401, 'Connect your account with connect_account or run: npx applydjinn-mcp login');
37
+ if (stored.expiresAt > Date.now() + 30_000) return stored.access_token;
38
+ return withCredentialLock(async () => {
39
+ const current = await readCredentials(); if (!current) throw new AgentApiError(401, 'Connect your account again.');
40
+ if (current.expiresAt > Date.now() + 30_000) return current.access_token;
41
+ const tokens = await requestJson('/api/agents/token', { body: { client_id: CLIENT_ID, resource: RESOURCE, grant_type: 'refresh_token', refresh_token: current.refresh_token } });
42
+ await saveCredentials(tokens); return tokens.access_token;
43
+ });
44
+ }
45
+ export async function callAgentTool(tool, args) {
46
+ const token = tool.scope === 'open' ? undefined : tool.scope === 'public:read' && process.env.APPLYDJIN_DATA_API_KEY ? process.env.APPLYDJIN_DATA_API_KEY : await accessToken();
47
+ const result = await requestJson('/api/agents/tools', { token, body: { name: tool.name, arguments: args } });
48
+ if (!result.success) throw new AgentApiError(400, 'The requested operation could not be completed.');
49
+ return result.data;
50
+ }
51
+ export async function connectionStatus() {
52
+ const stored = await readCredentials();
53
+ return { connected: !!stored && Date.parse(stored.refresh_expires_at) > Date.now(), scopes: stored?.scope?.split(' ') ?? [], expiresAt: stored?.refresh_expires_at ?? null,
54
+ environmentAccessToken: !!process.env.APPLYDJIN_AGENT_ACCESS_TOKEN, publicDataKeyConfigured: !!process.env.APPLYDJIN_DATA_API_KEY, manageUrl: ISSUER + '/account/agents' };
55
+ }
56
+ export async function disconnectAccount() {
57
+ let revoked = false;
58
+ try { const token = await accessToken(); revoked = !!(await requestJson('/api/agents/logout', { token })).success; }
59
+ catch { /* Local removal still works; report that remote revocation is unconfirmed. */ }
60
+ finally { await withCredentialLock(clearCredentials); }
61
+ return { localSignInRemoved: true, serverRevoked: revoked, manageUrl: ISSUER + '/account/agents', ...(revoked ? {} : { next: 'Revoke the connection on the website if it is still listed as active.' }) };
62
+ }
@@ -0,0 +1,56 @@
1
+ import { mkdir, lstat, open, readFile, rename, unlink, chmod } from 'node:fs/promises';
2
+ import { homedir } from 'node:os';
3
+ import { isAbsolute, join } from 'node:path';
4
+ import { randomUUID } from 'node:crypto';
5
+
6
+ export const configDirectory = () => { const path = process.env.APPLYDJIN_CONFIG_DIR || join(homedir(), '.config', 'applydjinn-mcp'); if (!isAbsolute(path)) throw new Error('Use an absolute private configuration directory.'); return path; };
7
+ const sessionFile = () => join(configDirectory(), 'session.json');
8
+ async function directory() {
9
+ const path = configDirectory(); await mkdir(path, { recursive: true, mode: 0o700 });
10
+ const stat = await lstat(path);
11
+ if (!stat.isDirectory() || stat.isSymbolicLink() || process.getuid && stat.uid !== process.getuid()) throw new Error('Use a configuration directory owned by your account, without symbolic links.');
12
+ if (process.platform !== 'win32') await chmod(path, 0o700);
13
+ return path;
14
+ }
15
+ export async function readCredentials() {
16
+ try {
17
+ await directory(); const stat = await lstat(sessionFile());
18
+ if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16_384 || process.getuid && stat.uid !== process.getuid() || process.platform !== 'win32' && (stat.mode & 0o077)) throw new Error('Unsafe credential file');
19
+ const value = JSON.parse(await readFile(sessionFile(), 'utf8'));
20
+ if (typeof value.access_token !== 'string' || typeof value.refresh_token !== 'string' || !Number.isFinite(value.expiresAt) || typeof value.connection_id !== 'string') throw new Error('Invalid session');
21
+ return value;
22
+ } catch (error) {
23
+ if (error.code === 'ENOENT') return null;
24
+ throw new Error('Saved sign-in is invalid or has unsafe file permissions. Use applydjinn-mcp login to reconnect.');
25
+ }
26
+ }
27
+ export async function saveCredentials(tokens) {
28
+ await directory();
29
+ if (typeof tokens.access_token !== 'string' || typeof tokens.refresh_token !== 'string' || !Number.isFinite(tokens.expires_in) || !tokens.connection_id) throw new Error('Invalid sign-in response');
30
+ const path = join(configDirectory(), `.session-${randomUUID()}.tmp`);
31
+ const file = await open(path, 'wx', 0o600);
32
+ try { await file.writeFile(JSON.stringify({ ...tokens, expiresAt: Date.now() + tokens.expires_in * 1000 })); await file.sync(); }
33
+ finally { await file.close(); }
34
+ try { await rename(path, sessionFile()); }
35
+ catch (error) { await unlink(path).catch(() => {}); throw error; }
36
+ }
37
+ export async function clearCredentials() { await unlink(sessionFile()).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
38
+ export async function withCredentialLock(action) {
39
+ const path = join(await directory(), 'session.lock'); let file;
40
+ for (let attempt = 0; attempt < 40; attempt++) {
41
+ try { file = await open(path, 'wx', 0o600); break; }
42
+ catch (error) {
43
+ if (error.code !== 'EEXIST') throw new Error('Could not lock the saved sign-in.');
44
+ const stat = await lstat(path).catch(() => null);
45
+ if (stat && !stat.isSymbolicLink() && Date.now() - stat.mtimeMs > 60_000 && (!process.getuid || stat.uid === process.getuid())) await unlink(path).catch(() => {});
46
+ await new Promise(resolve => setTimeout(resolve, 150));
47
+ }
48
+ }
49
+ if (!file) throw new Error('Another client is refreshing your sign-in. Retry shortly.');
50
+ const owned = await file.stat();
51
+ try { return await action(); }
52
+ finally {
53
+ await file.close(); const current = await lstat(path).catch(() => null);
54
+ if (current && current.ino === owned.ino) await unlink(path).catch(() => {});
55
+ }
56
+ }
package/lib/login.mjs ADDED
@@ -0,0 +1,69 @@
1
+ import { createServer } from 'node:http';
2
+ import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
3
+ import { spawn } from 'node:child_process';
4
+ import { apiOrigin, CLIENT_ID, ISSUER, RESOURCE, requestJson } from './api.mjs';
5
+ import { saveCredentials, readCredentials, clearCredentials, withCredentialLock } from './credentials.mjs';
6
+
7
+ let pending;
8
+ const nonce = () => randomBytes(32).toString('base64url');
9
+ function openBrowser(url) {
10
+ const command = process.platform === 'darwin' ? '/usr/bin/open' : process.platform === 'win32' ? 'explorer.exe' : 'xdg-open';
11
+ try { const child = spawn(command, [url], { detached: true, stdio: 'ignore', shell: false }); child.on('error', () => {}); child.unref(); } catch { /* The returned URL can be opened manually. */ }
12
+ }
13
+ const page = (message, ok) => '<!doctype html><html lang="en"><meta charset="utf-8"><meta name="referrer" content="no-referrer"><title>ApplyDjinn agent connection</title><body style="font-family:system-ui;max-width:600px;margin:15vh auto;padding:24px"><h1>' + (ok ? 'Agent connected' : 'Connection not completed') + '</h1><p>' + message + '</p><p>You can close this tab.</p><script>history.replaceState(null,"","/complete")</script></body></html>';
14
+ export async function beginLogin({ readOnly = false, documents = false, clientName = 'ApplyDjinn MCP', open = true, timeoutMs = 300_000 } = {}) {
15
+ const requestKey = JSON.stringify([readOnly, documents, clientName]);
16
+ if (pending?.requestKey === requestKey) return { url: pending.url, promise: pending.promise };
17
+ if (pending) pending.cancel();
18
+ const verifier = nonce(); const state = nonce(); let finished = false; let cancelled = false; let redirectUri; let timer; let active; let work = Promise.resolve();
19
+ const clearPending = () => { if (pending === active) pending = undefined; };
20
+ let resolve; let reject;
21
+ const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
22
+ // A tool may return before the browser approval; retain a handled promise.
23
+ promise.catch(() => {});
24
+ const server = createServer({ maxHeaderSize: 8192 }, async (request, response) => {
25
+ response.setHeader('Cache-Control', 'no-store'); response.setHeader('Referrer-Policy', 'no-referrer');
26
+ response.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; frame-ancestors 'none'");
27
+ response.setHeader('Content-Type', 'text/html; charset=utf-8');
28
+ if (!redirectUri) { response.writeHead(503); response.end(); return; }
29
+ let url; try { url = new URL(request.url ?? '/', redirectUri); } catch { response.writeHead(400); response.end(); return; }
30
+ const expectedHost = new URL(redirectUri).host;
31
+ if (request.method !== 'GET' || request.headers.host !== expectedHost || url.pathname !== '/callback' || finished) { response.writeHead(404); response.end('Not found'); return; }
32
+ const receivedState = url.searchParams.get('state') ?? '';
33
+ if (!/^[A-Za-z0-9_-]{43}$/.test(receivedState) || !timingSafeEqual(Buffer.from(receivedState), Buffer.from(state)) || url.searchParams.get('iss') !== ISSUER) { response.writeHead(400); response.end('Invalid authorization response'); return; }
34
+ const code = url.searchParams.get('code') ?? '';
35
+ if (!/^[A-Za-z0-9_-]{43}$/.test(code)) { response.writeHead(400); response.end('Invalid authorization code'); return; }
36
+ finished = true;
37
+ work = (async () => {
38
+ let tokens;
39
+ try {
40
+ tokens = await requestJson('/api/agents/token', { body: { client_id: CLIENT_ID, resource: RESOURCE, grant_type: 'authorization_code', code, code_verifier: verifier, redirect_uri: redirectUri } });
41
+ if (cancelled) throw new Error('Cancelled');
42
+ await withCredentialLock(async () => { if (cancelled) throw new Error('Cancelled'); await saveCredentials(tokens); });
43
+ if (cancelled) throw new Error('Cancelled');
44
+ response.end(page('Return to your AI client. Your sign-in is saved locally with private file permissions.', true));
45
+ resolve({ connected: true, scopes: tokens.scope.split(' '), expiresAt: tokens.refresh_expires_at });
46
+ } catch {
47
+ if (tokens?.access_token) {
48
+ // Remove only this flow's credentials; a newer login may have won.
49
+ await withCredentialLock(async () => { const saved = await readCredentials(); if (saved?.connection_id === tokens.connection_id) await clearCredentials(); }).catch(() => {});
50
+ await requestJson('/api/agents/logout', { token: tokens.access_token }).catch(() => {});
51
+ }
52
+ if (!response.destroyed) { response.writeHead(400); response.end(page('Please start the connection again from your AI client.', false)); }
53
+ reject(new Error(cancelled ? 'Agent sign-in was cancelled or expired.' : 'The agent connection could not be completed. Start login again.'));
54
+ } finally { clearTimeout(timer); server.close(); clearPending(); }
55
+ })();
56
+ await work;
57
+ });
58
+ await new Promise((yes, no) => { server.once('error', no); server.listen(0, '127.0.0.1', yes); });
59
+ redirectUri = `http://127.0.0.1:${server.address().port}/callback`;
60
+ const url = new URL('/connect/agent', apiOrigin());
61
+ const scopes = ['public:read', 'account:read', 'profile:read', ...(!readOnly ? ['profile:write'] : []), ...(documents ? ['documents:read'] : [])];
62
+ for (const [key, value] of Object.entries({ client_id: CLIENT_ID, resource: RESOURCE, client_name: clientName.slice(0, 80), redirect_uri: redirectUri,
63
+ code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256', state, scope: scopes.join(' ') })) url.searchParams.set(key, value);
64
+ const cancel = () => { cancelled = true; finished = true; clearTimeout(timer); server.close(); reject(new Error('Agent sign-in was cancelled or expired.')); clearPending(); return work; };
65
+ timer = setTimeout(cancel, timeoutMs); active = { url: url.toString(), promise, cancel, requestKey }; pending = active;
66
+ if (open) openBrowser(url.toString());
67
+ return { url: url.toString(), promise };
68
+ }
69
+ export function cancelLogin() { return pending?.cancel(); }
package/lib/server.mjs ADDED
@@ -0,0 +1,59 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { Server, fromJsonSchema } from '@modelcontextprotocol/server';
3
+ import { callAgentTool, connectionStatus, disconnectAccount, AgentApiError } from './api.mjs';
4
+ import { beginLogin, cancelLogin } from './login.mjs';
5
+
6
+ export const remoteTools = JSON.parse(readFileSync(new URL('./tools.json', import.meta.url), 'utf8'));
7
+ const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
8
+ const localTools = [
9
+ { name: 'connect_account', title: 'Connect your ApplyDjinn account', description: 'Open a browser for sign-in and explicit account/profile permissions. Returns the approval URL; check connection_status after the user approves. Passwords and tokens are never tool arguments.',
10
+ inputSchema: { type: 'object', properties: { readOnly: { type: 'boolean', default: false }, documents: { type: 'boolean', default: false }, clientName: { type: 'string', minLength: 1, maxLength: 80 } }, additionalProperties: false },
11
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true } },
12
+ { name: 'connection_status', title: 'Check your account connection', description: 'Show granted permissions and expiry without returning credentials or loading private profile information.', inputSchema: { type: 'object', properties: {}, additionalProperties: false },
13
+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } },
14
+ { name: 'disconnect_account', title: 'Disconnect your account', description: 'Revoke this agent connection and remove locally saved credentials. Requires the user to request disconnection and confirm=true.', inputSchema: { type: 'object', properties: { confirm: { const: true, type: 'boolean' } }, required: ['confirm'], additionalProperties: false },
15
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false } },
16
+ ];
17
+ export const allTools = [...remoteTools, ...localTools];
18
+ const validators = new Map(allTools.map(tool => [tool.name, fromJsonSchema(tool.inputSchema)]));
19
+ export function createApplyDjinnServer() {
20
+ const server = new Server({ name: 'applydjinn-mcp', version, title: 'ApplyDjinn', websiteUrl: 'https://applydjinn.com/mcp-server' }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
21
+ server.setRequestHandler('tools/list', async () => ({ tools: allTools.map(({ scope: _scope, ...tool }) => tool) }));
22
+ server.setRequestHandler('tools/call', async request => {
23
+ const name = request.params.name; const tool = allTools.find(t => t.name === name);
24
+ if (!tool) return failure('Unknown ApplyDjinn tool.');
25
+ const parsed = await validators.get(name)['~standard'].validate(request.params.arguments ?? {});
26
+ if (parsed.issues) return failure('Invalid tool arguments.', { issues: parsed.issues.map(i => ({ message: i.message, path: i.path })).slice(0, 8) });
27
+ try {
28
+ let data;
29
+ if (name === 'connect_account') {
30
+ const started = await beginLogin(parsed.value);
31
+ data = { approvalUrl: started.url, requestedPermissions: new URL(started.url).searchParams.get('scope').split(' '), next: 'The user must sign in and approve in the browser. Then call connection_status.', expiresInSeconds: 300 };
32
+ } else if (name === 'connection_status') data = await connectionStatus();
33
+ else if (name === 'disconnect_account') { await cancelLogin(); data = await disconnectAccount(); }
34
+ else data = await callAgentTool(tool, parsed.value);
35
+ return { content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: { data } };
36
+ } catch (error) {
37
+ return failure(error instanceof Error ? error.message : 'The request could not be completed.', error instanceof AgentApiError ? { status: error.status, ...error.details } : {});
38
+ }
39
+ });
40
+ server.setRequestHandler('resources/list', async () => ({ resources: [{ uri: 'applydjinn://documentation', name: 'ApplyDjinn MCP setup and data interpretation', mimeType: 'text/plain' }] }));
41
+ server.setRequestHandler('resources/read', async request => {
42
+ if (request.params.uri !== 'applydjinn://documentation') throw new Error('Unknown resource');
43
+ return { contents: [{ uri: request.params.uri, mimeType: 'text/plain', text: 'Setup, permissions and examples: https://applydjinn.com/mcp-server\nPreserve first-party page links, source attribution and observation dates. Research describes the observed catalog, not the whole market.\nAccount access is optional and user-approved. Manage it at https://applydjinn.com/account/agents' }] };
44
+ });
45
+ server.setRequestHandler('prompts/list', async () => ({ prompts: [
46
+ { name: 'job_search', description: 'Find relevant roles and return evidence with direct ApplyDjinn links.', arguments: [{ name: 'query', required: true }] },
47
+ { name: 'interview_practice', description: 'Practice original questions with their source lessons.', arguments: [{ name: 'topic', required: true }] },
48
+ ] }));
49
+ server.setRequestHandler('prompts/get', async request => {
50
+ const args = request.params.arguments ?? {};
51
+ let text;
52
+ if (request.params.name === 'job_search') text = `Find relevant ApplyDjinn vacancies for ${String(args.query ?? '').slice(0, 200)}. Use search_vacancies and company_hiring_activity. Include direct ApplyDjinn vacancy/company links, observation dates and evidence gaps. Do not invent requirements or apply to an employer.`;
53
+ else if (request.params.name === 'interview_practice') text = `Help me practice ${String(args.topic ?? '').slice(0, 200)} using search_lessons, get_lesson, search_guides and interview_questions. Show one question at a time, retain the source lesson link, and reveal answers after I attempt it.`;
54
+ else throw new Error('Unknown prompt');
55
+ return { messages: [{ role: 'user', content: { type: 'text', text } }] };
56
+ });
57
+ return server;
58
+ }
59
+ function failure(message, details = {}) { const data = { error: message, ...details }; return { isError: true, content: [{ type: 'text', text: JSON.stringify(data) }] }; }
package/lib/tools.json ADDED
@@ -0,0 +1 @@
1
+ [{"name":"search_vacancies","title":"Search public vacancies","description":"Search active ApplyDjinn vacancies by keywords, skills, location, category, or work format.","inputSchema":{"type":"object","properties":{"search":{"type":"string","maxLength":500},"skills":{"type":"array","items":{"type":"string"},"maxItems":20},"locations":{"type":"array","items":{"type":"string"},"maxItems":20},"category":{"type":"string"},"workFormat":{"type":"string","enum":["remote","office","hybrid"]},"page":{"type":"integer","minimum":1,"default":1},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"scope":"public:read"},{"name":"get_vacancy","title":"Get a public vacancy","description":"Get one active vacancy summary with source attribution and normalized public fields. The original posting URL is not published.","inputSchema":{"type":"object","properties":{"id":{"type":"integer","minimum":1}},"required":["id"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"scope":"public:read"},{"name":"technology_demand","title":"Measure technology demand","description":"Return vacancy demand and evidence tiers for a technology, optionally filtered by location.","inputSchema":{"type":"object","properties":{"technology":{"type":"string","minLength":1,"maxLength":100},"locations":{"type":"array","items":{"type":"string"},"maxItems":20}},"required":["technology"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"scope":"public:read"},{"name":"compare_technologies","title":"Compare technology demand","description":"Compare demand for two to ten technologies on the same catalog scope.","inputSchema":{"type":"object","properties":{"technologies":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":2,"maxItems":10},"locations":{"type":"array","items":{"type":"string"},"maxItems":20}},"required":["technologies"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"scope":"public:read"},{"name":"company_hiring_activity","title":"Find company hiring activity","description":"Find companies and their active role counts and leading technologies.","inputSchema":{"type":"object","properties":{"company":{"type":"string","maxLength":500},"location":{"type":"string","maxLength":255},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"scope":"public:read"},{"name":"market_snapshot","title":"Get the ApplyDjinn market snapshot","description":"Return current catalog coverage, quality indicators, observation window, and top technologies.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"scope":"public:read"},{"name":"find_links","title":"Find ApplyDjinn pages","description":"Get first-party destination links for vacancies, companies, news, courses and interview guides. No account is required.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","maxLength":200},"section":{"default":"all","type":"string","enum":["all","vacancies","companies","news","learning","guides"]}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_courses","title":"Explore engineering courses","description":"List courses and their cover previews, lesson counts and website links. Does not download course content.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","maxLength":200},"limit":{"default":50,"type":"integer","minimum":1,"maximum":50}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"search_lessons","title":"Search lessons","description":"Search lesson titles and tags across the course catalog, returning exact ApplyDjinn lesson URLs.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":200},"courseId":{"type":"string","minLength":1,"maxLength":120},"limit":{"default":10,"type":"integer","minimum":1,"maximum":30}},"required":["query"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_course","title":"Get a course outline","description":"Get the complete lesson outline and links for one course. Lesson bodies are fetched only when requested.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"courseId":{"type":"string","minLength":1,"maxLength":120}},"required":["courseId"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_lesson","title":"Read an engineering lesson","description":"Read one lesson with explanations, worked code, prepared results and practice questions. Answers are included only when requested.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"courseId":{"type":"string","minLength":1,"maxLength":120},"lessonId":{"type":"string","minLength":1,"maxLength":120},"includeAnswers":{"default":false,"type":"boolean"}},"required":["courseId","lessonId"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"interview_questions","title":"Practice interview questions","description":"Get original ApplyDjinn self-check questions with their lesson links, optionally including answers and explanations.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"courseId":{"default":"interview","type":"string","minLength":1,"maxLength":120},"query":{"type":"string","maxLength":200},"limit":{"default":5,"type":"integer","minimum":1,"maximum":20},"includeAnswers":{"default":false,"type":"boolean"}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"search_guides","title":"Find career and interview guides","description":"Find original career guides, company interview preparation and worked practice exercises with direct links.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","maxLength":200},"limit":{"default":10,"type":"integer","minimum":1,"maximum":30}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_guide","title":"Read a career or interview guide","description":"Read one original ApplyDjinn guide, including exercises, worked examples and source attribution.","scope":"open","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":120}},"required":["slug"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"search_news","title":"Read company news summaries","description":"Get attributed news summaries and direct ApplyDjinn article/company links. Does not return publisher article bodies.","scope":"public:read","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","maxLength":200},"companyId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"days":{"default":30,"anyOf":[{"type":"number","const":7},{"type":"number","const":30},{"type":"number","const":90}]},"page":{"default":1,"type":"integer","minimum":1,"maximum":1000},"limit":{"default":10,"type":"integer","minimum":1,"maximum":30}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_account","title":"Read your account","description":"Read the connected user's email, workspace and credit balance. Requires explicit account access.","scope":"account:read","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_profile","title":"Read your complete profile","description":"Read your connected profile, skills, experience, education, languages, certificates, portfolio and showcase. No other user's ID can be supplied.","scope":"profile:read","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"update_profile","title":"Fill or edit your profile","description":"Update supplied profile fields and keep other fields. This tool does not change public visibility or active-search settings. Requires profile editing permission.","scope":"profile:write","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"targetRole":{"type":"string","maxLength":255},"category":{"type":"string","maxLength":100},"subcategories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":100}},"experienceYears":{"type":"integer","minimum":0,"maximum":60},"salaryExpectation":{"type":"integer","minimum":0,"maximum":9007199254740991},"salaryCurrency":{"type":"string","maxLength":10},"salaryTaxType":{"type":"string","enum":["net","gross"]},"hourlyRate":{"type":"integer","minimum":0,"maximum":9007199254740991},"workFormats":{"type":"array","items":{"type":"string","enum":["remote","office","hybrid"]}},"employmentTypes":{"type":"array","items":{"type":"string","enum":["full-time","part-time","contract","freelance"]}},"locationCountry":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"locationCity":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"desiredLocations":{"maxItems":20,"type":"array","items":{"type":"string","minLength":2,"maxLength":160}},"relocationReady":{"type":"boolean"},"baseCvText":{"type":"string","maxLength":32000},"baseCoverLetterText":{"type":"string","maxLength":16000}},"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"update_profile_identity","title":"Edit your name and phone","description":"Edit your first name, last name and phone using the current identity version from get_profile. Keeps publication and an existing public address unchanged; the first address is free and stays unpublished. Never spends credits.","scope":"profile:write","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"firstName":{"type":"string","maxLength":80,"pattern":"^[^<>\\u0000-\\u001f]*$"},"lastName":{"type":"string","maxLength":80,"pattern":"^[^<>\\u0000-\\u001f]*$"},"phone":{"type":"string","maxLength":40,"pattern":"^[^<>\\u0000-\\u001f]*$"},"expectedVersion":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["expectedVersion"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"save_profile_item","title":"Add or edit a profile item","description":"Add a profile item; provide id to edit an owned item. Read get_profile for IDs. data fields: skill(skillName,experienceYears,proficiencyLevel); experience(company,role,startDate,endDate,description,domain); education(institution,degree,field,startDate,endDate); language(language,proficiencyLevel); certification(name,issuer,dateObtained,expiryDate); portfolio(type,url,title); agentic_tool(name or skillId,experienceMonths).","scope":"profile:write","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"kind":{"type":"string","enum":["skill","experience","education","language","certification","portfolio","agentic_tool"]},"id":{"type":"string","minLength":1,"maxLength":120},"data":{"type":"object","propertyNames":{"type":"string","maxLength":80},"additionalProperties":{"$ref":"#/$defs/__schema0"}}},"required":["kind","data"],"additionalProperties":false,"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]}}},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"delete_profile_item","title":"Remove an owned profile item","description":"Remove exactly one owned profile item after the user asks for its deletion. Requires confirm=true and profile editing permission.","scope":"profile:write","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"kind":{"type":"string","enum":["skill","experience","education","language","certification","portfolio","agentic_tool"]},"id":{"type":"string","minLength":1,"maxLength":120},"confirm":{"type":"boolean","const":true}},"required":["kind","id","confirm"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false}},{"name":"update_profile_showcase","title":"Edit your profile introduction","description":"Set the profile headline, introduction, selected course IDs and CV links. Supply the complete showcase from get_profile; publication settings are unchanged.","scope":"profile:write","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"headline":{"type":"string","maxLength":100},"introduction":{"type":"string","maxLength":1200},"courseIds":{"maxItems":13,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"cvLinks":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","maxLength":2048,"format":"uri"}},"required":["title","url"],"additionalProperties":false}}},"required":["headline","introduction","courseIds","cvLinks"],"additionalProperties":false},"annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_documents","title":"List your saved documents","description":"List the connected user's saved application documents and private workspace links.","scope":"documents:read","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"default":10,"type":"integer","minimum":1,"maximum":30}},"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_document","title":"Read your saved document","description":"Read one saved application document owned by the connected user. Requires separate document-reading permission.","scope":"documents:read","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120}},"required":["id"],"additionalProperties":false},"annotations":{"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}}]
package/package.json CHANGED
@@ -1,6 +1,16 @@
1
1
  {
2
2
  "name": "applydjinn-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "Official ApplyDjinn MCP server: tech jobs, companies, news, engineering lessons, interview practice and user-authorized profile editing for AI agents.",
5
+ "type": "module",
6
+ "bin": { "applydjinn-mcp": "bin/applydjinn-mcp.mjs" },
7
+ "files": ["bin/", "lib/", "README.md", "LICENSE"],
8
+ "engines": { "node": ">=20" },
9
+ "dependencies": { "@modelcontextprotocol/server": "2.4.0" },
10
+ "devDependencies": { "@modelcontextprotocol/client": "2.4.0" },
11
+ "scripts": { "test": "node --test test/*.test.mjs", "prepublishOnly": "npm test" },
12
+ "homepage": "https://applydjinn.com/mcp-server",
13
+ "bugs": { "url": "https://applydjinn.com/contact" },
14
+ "license": "MIT",
15
+ "keywords": ["mcp", "mcp-server", "model-context-protocol", "applydjinn", "ai-agent", "tech-jobs", "job-search", "hiring", "companies", "company-news", "engineering", "lessons", "interview", "career", "profile"]
16
+ }